Device information

Device name

TriSpectorP

Firmware version

4.2.0.214R

Date

2020-03-30

Crowns

C

Cipher Cipher.AES Cipher.Certificate Cipher.Certificate.SigningRequest Cipher.Key Cipher.RSA Command Command.Client Command.Methods Connector Connector.DigitalIn Connector.DigitalOut Connector.DigitalOut.DelayedEvents Connector.Increment Container

D

DateTime DigitalLogic DigitalLogic.Delay DigitalLogic.EdgeDetector DigitalLogic.Gate DigitalLogic.TFlipFlop

E

Encoder Engine Engine.AsyncFunction Engine.AsyncFunction.Future Engine.Event Engine.EventBinding Engine.FunctionBinding Engine.SyncEvent Engine.WebServer

F

FTPClient FTPServer FieldBus File File.Archive File.Archive.ZIP

H

Halcon Halcon.Result Hash Hash.CRC32 Hash.MD5 Hash.SHA256

I

Image Image.Calibration Image.Calibration.CameraModel Image.Calibration.Correction Image.Fixture Image.Fixture3D Image.Format Image.Format.BMP Image.Format.JPEG Image.Format.PNG Image.Matching Image.Matching.EdgeMatcher Image.Matching.EdgeMatcher3D Image.Matching.PatternMatcher Image.Matching.PatternVerifier Image.Matching.PointMatcher Image.OCR Image.OCR.Halcon Image.OCR.Halcon.AutoSegmenter Image.OCR.Halcon.FontClassifier Image.OCR.Halcon.ManualSegmenter Image.OCR.Halcon.SegmenterResult Image.PixelRegion Image.PixelRegion.Filter Image.Provider Image.Provider.Camera Image.Provider.Camera.V3TConfig2D Image.Provider.Camera.V3TConfig3D Image.Provider.Directory Image.Pyramid Image.ShapeFitter Image.SurfaceFitter

L

LED LUA.debug LUA.math LUA.string LUA.table LUA.utf8 Log Log.Handler Log.Logger Log.SharedLogger

M

MachineLearning MachineLearning.Bayes MachineLearning.DataSet MachineLearning.Fisher MachineLearning.KMeansClustering MachineLearning.KNearestNeighbors MachineLearning.NeuralNet MachineLearning.RandomForest MachineLearning.SupportVectorMachine Matrix Mesh Monitor Monitor.App Monitor.CPU Monitor.Memory Monitor.Network

N

NTPClient

O

OPCUA OPCUA.Server OPCUA.Server.EndpointConfiguration OPCUA.Server.FileCertificateStoreConfiguration OPCUA.Server.Namespace OPCUA.Server.Node OPCUA.Server.SecurityConfiguration OPCUA.Server.ServerConfiguration OPCUA.Server.UserTokenDatabase OPCUA.Server.Value Object

P

Parameters Parameters.Listener Parameters.Node Parameters.Validator Point PointCloud PointCloud.Matching PointCloud.Matching.Halcon PointCloud.Matching.Halcon.SurfaceMatcher PointCloud.RangeFilter Profile Profile.Curve Profile.CurveFitter Profile.Log Profile.Matching Profile.Matching.PatternMatcher

S

Script Script.Queue SensorData SerialCom Shape Shape.Composite Shape3D Statistics

T

TCPIPClient TCPIPServer TCPIPServer.Connection Text Timer Transform TriSpector

U

UDPSocket

V

View View.Camera View.ColorMap View.GraphDecoration View.ImageDecoration View.MeshDecoration View.PixelRegionDecoration View.PointCloudDecoration View.ShapeDecoration View.TextDecoration

Cipher

Short description

Namespace for different kinds of en- and decryption ciphers

Overview

Cipher.AES

Short description

AES cipher support

Overview

Functions

decrypt()
Short description

Decrypts AES-encrypted data (OpenAES compatible)

Parameters
Name Type Description

encryptedData

BINARY

The AES encrypted data to be decrypted

key

BINARY

The decryption key. Has to be 16, 24, or 32 bytes long (= 128, 192 or 256 bits)

Return values
Name Type Description

decryptedData

BINARY

The decrypted result. When any encryption stage goes wrong, or an invalid AES key is passed, an empty binary result is returned

Sample
decrypted = Cipher.AES.decrypt(encryptedData, key)
encrypt()
Short description

Encrypts data. The mode of operation is CBC. An IV is generated randomly and stored in a OpenAES-compatible header that is part of the ciphertext (return value).

Parameters
Name Type Description

data

BINARY

The data to be encrypted

key

BINARY

The encryption key. Has to be 16, 24, or 32 bytes long (= 128, 192 or 256 bits)

Return values
Name Type Description

encryptedData

BINARY

The encrypted result. When any decryption stage goes wrong, or an invalid AES key is passed, an empty binary result is returned

Sample
encrypted = Cipher.AES.encrypt(data, key)

Cipher.Certificate

Short description

Functionality to work with X.509 certificates.

Cipher.Certificate.SigningRequest

Short description

Allows to generate certificate signing requests according to the PKCS #10 specification.

Functions

addSubjectField()
Short description

Adds a field to the subject of the certificate signing request. The subject of the certificate can consist of multiple fields, each field being a key/value-pair.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

subjectField

STRING

The subject field to add

value

STRING

The value for this subject field

Return values
Name Type Description

success

BOOL

Returns 'true' if subjectField could be added successfully.

Sample
Cipher.Certificate.SigningRequest.addSubjectField(handle, "CN", "myCommonName")
create()
Short description

Creates a new certificate signing request instance.

Return values
Name Type Description

handle

HANDLE

The instance handle for the certificate signing request.

Sample
local csr = Cipher.Certificate.SigningRequest.create()
encode()
Short description

Encodes the signed certificate signing request into a binary buffer.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

format

ENUM Format

Optional passphrase.

Return values
Name Type Description

csr

BINARY

Returns binary representation of the certificate signing request, or nil on error.

Sample
local success = Cipher.Certificate.SigningRequest.encode(handle)
setKeyPair()
Short description

Sets the public key that will be included in the signing request and the private key that will be used to sign the request.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

publicKey

OBJECT Cipher.Key

The public key to include in the certificate signing request.

privateKey

OBJECT Cipher.Key

The private key which is used to sign the certificate signing request.

Return values
Name Type Description

success

BOOL

Returns 'true' if key pair could be loaded successfully.

Sample
Cipher.Certificate.SigningRequest.setKeyPair(handle, publicKey, privateKey)

Cipher.Key

Short description

Represents a key to be used in public-key cryptosystem.

Overview

Functions

encode()
Short description

Encodes a key into a binary buffer.

Parameters
Name Type Description

key

OBJECT Cipher.Key

The instance object to use

format

ENUM Format

Optional passphrase.

passphrase

STRING

Optional passphrase. Ignored if this is not a private key.

Return values
Name Type Description

buffer

BINARY

Returns binary representation of the key, or nil on error.

Sample
local keyBuf = Cipher.Key.encode(key, "PEM", "mypassphrase")

Cipher.RSA

Short description

RSA public-key cryptosystem support.

Functions

generateKeyPair()
Short description

Generates a RSA key pair and stores the keys in PEM file format.

Parameters
Name Type Description

size

INT

Length of the modulus in bits. Typical sizes are 2048 or 4096.

Return values
Name Type Description

publicKey

OBJECT Cipher.Key

The generated public key. Nil in case of error.

privateKey

OBJECT Cipher.Key

The generated private key. Nil in case of error.

Sample
local publicKey, privateKey = Cipher.RSA.generateKeyPair(2048)

Command

Short description

Command handling functionalities

Overview

Functions

Command.Client

Short description

A client to connect to a command server and execute SOPAS commands. Command servers can be other devices which speak SOPAS CoLaA, CoLaB or CoLa2. A client can execute single commands on the device and also can store and restore parameters of it. To be able to talk with a device, a ".sopas" file is needed to be specified with the "Command.Client.setDescription" function. A ".sopas" file can be created using SOPAS ET and store a project. The connection to the device must be injected using the "setConnection" function by providing a handle to a connection which is already open and configured. Connections must be CROWNs which have a "transmit" function and an "OnReceive" event, e.g. "TCPIPClient" and "SerialCom". The handling of disconnects can be handled by the user. There is a default timeout for every request of 30 seconds. If the connection is lost or no response is received, the requests return with an error after that time. There is a fix internal maximum CoLa de/serialization buffer size of 64k. Request bigger than this are not possible.

Functions

backup()
Short description

Stores the parameters of a device to a ".sopas" file. This is useful to backup the parameters of a device to a file to restore it later or to open it in SOPAS ET. If storing fails no file is created at all. The opposite function is "restore" to put all parameters to a device.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

paramFile

STRING

The path to the .sopas file to store to

Return values
Name Type Description

success

BOOL

True if successful stored the parameters to the file. False if not possible or failed while storing.

errMsg

STRING

If backup fails, this string contains the readable error message about why it failed

Sample
local bSuccess = Command.Client.backup(handle, "private/myDevice.sopas")
close()
Short description

Forces a close from the server. Can be used to shut down the communication and reconfigure the "Command.Client"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

Sample
Command.Client.close(handle)
create()
Short description

Creates a new Command.Client instance. The client needs to be configured before using the Open()-function.

Return values
Name Type Description

handle

HANDLE

The new instance

Sample
-- Create and configure the connection
conHandle = TCPIPClient.create()
TCPIPClient.setIPAddress(conHandle, "192.168.0.1")
TCPIPClient.connect(conHandle)
assert( TCPIPClient.isConnected(conHandle) ) -- connection handling has to be done by the user of the Command.Client

-- Create, configure and open the client
handle = Command.Client.create()
Command.Client.setDescriptionFile(handle, "resources/myDevice.sopas")
Command.Client.setProtocol(handle, "COLA_A")
Command.Client.setConnection(handle, conHandle)
assert ( Command.Client.open(handle) )
-- Now the ".sopas"-file is loaded and the client is registered at the connection and can be used

-- read a variable from the device
local paramNode = Command.Client.read(handle, "DeviceIdent")
if paramNode then
  local devName = Parameters.Node.get(paramNode, "Name")
  print("Device name is " .. devName)
end
createNode()
Short description

Creates a new Parameters.Node with a defined structure for a variable or as method argument. This can be used for write or invoke calls.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

paramName

STRING

The communication name of the variable or method.

Return values
Name Type Description

paramNode

OBJECT Parameters.Node

The new created not if exists

Sample
local newNode = Command.Client.createNode(handle, "theParameterName")
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

disableChangeListener()
Short description

Removes the registration for a variable change

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventName

STRING

The communication name of the variable.

Return values
Name Type Description

success

BOOL

True if successfully disabled. False if was not enabled before, timed out or error

Sample
local bSuccess = Command.Client.disableChangeListener(handle, "theEventName")
enableChangeListener()
Short description

Register for variable change of the device. All incoming changes are directly received after this call, therefore use the "register" function to register for the "OnChanged" event before.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventName

STRING

The communication name of the variable.

Return values
Name Type Description

success

BOOL

True if successfully registered. False if already registered, timed out or error

Sample
local bSuccess = Command.Client.enableChangeListener(handle, "theEventName")
getDevicesFromDescriptionFile()
Short description

Retrieve the names of the devices, that are stored within the description file previously set with setDescriptionFile.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

Return values
Name Type Description

deviceNames

STRING

A vector containing all the found device names. Empty names are also valid values. Nil is returned, if the description file was not set or is not parseable. An Empty vector is empty, if the description file was loaded successfully but does not contain any devices.

Sample
Command.Client.getDevicesFromDescriptionFile(handle)
getVariantsForDeviceFromDescriptionFile()
Short description

Retrieve all possible variants for a device stored in the previously set with setDescriptionFile.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

deviceName

STRING

The name of the device to get the variants for. Should be a value which was previously returned by getDevicesFromDescriptionFile.

Return values
Name Type Description

variantNames

STRING

A vector containing all the found variant names. For a device without variants, a vector with a single, emtpy variant name is returned. Nil is returned, if the description file was not set or is not parseable.

Sample
Command.Client.getVariantsForDeviceFromDescriptionFile(handle, "DeviceName")
invoke()
Short description

Invokes a method on the device and waits until it is finished. If the method has arguments the createNode function can be used to set them and pass to this function.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

methodName

STRING

The communication name of the method.

paramNode

CONST_OBJECT Parameters.Node

The node value as arguments if the method has arguments

Return values
Name Type Description

success

BOOL

True if successfully executed. False if timeout or error

paramNode

OBJECT Parameters.Node

The method return values if the method has return values

Sample
local methodArg = Command.Client.createNode(handle, "theMethodName")
local bSuccess,methodResults = Command.Client.invoke(handle, "theMethodName", methodArg)
open()
Short description

Opens the client with the current configuration and makes usage possible. The configuration values have to be set before calling this function. The open()-function sends no command to device, just loads the configuration and make communication with device possible.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

Return values
Name Type Description

success

BOOL

True if successfully opened. False if configuration isn’t valid (e.g. wrong description file)

errMsg

STRING

If open fails, this string contains the readable error message about why it failed

Sample
local bSuccess = Command.Client.open(handle)
read()
Short description

Reads a parameter of the connected device and returns its value

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

varName

STRING

The communication name of the variable

Return values
Name Type Description

paramNode

OBJECT Parameters.Node

The copy of the value. Nil if not exists or was not possible to read.

Sample
local paramNode = Command.Client.read(handle, "theParameterName")
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

restore()
Short description

Restores the parameters from a ".sopas" file to the device. This is useful to configure the device in a specific state. If restoring fails the device might be in an inconsistent configuration. The variables are only restored which match the current login level. So make sure to login to the device in the wanted userlevel before. Variables which are above the current userlevel are not written. The opposite function is "backup" to get all parameters from a device.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

paramFile

STRING

The path to the .sopas file to restore from

Return values
Name Type Description

success

BOOL

True if successful restored all parameters. False if not possible or failed while restoring.

errMsg

STRING

If restore fails, this string contains the readable error message about why it failed

Sample
local bSuccess = Command.Client.restore(handle, "resources/myDevice.sopas")
setAccessMode()
Short description

Sets the access mode to use for every request. It depends on the devices if requests by name is possible or not. Smaller devices might only support requests by index. Default is 'by name'. The value can also be changed on the fly when the client is open.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

accessMode

ENUM AccessMode

The access mode to use to the device.

Sample
Command.Client.setAccessMode(handle, "BY_INDEX")
setByteOrder()
Short description

Sets the CoLa byte order to use for binary cola protocols (CoLaB,CoLa2). Defaults is 'Big-endian'.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

byteOrder

ENUM ByteOrder

The cola byte order to use to the device.

Sample
Command.Client.setByteOrder(handle, "LITTLE_ENDIAN")
setConnection()
Short description

Sets the connection handle to use for talking with the device. The handle can be of any connection CROWN which serves a "transmit" function and an "OnReceive" event. The connection has already to be opened before and can be control by the user. Also make sure that the connection has to be set to no framing which is the default for most connections. The Client does the framing on its own, so check the setFraming function of the connection. If the connection throws too much receive data, there is a queue of 10 packets and everything more than this is thrown away.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

conHandle

HANDLE

The connection handle to use to communicate with the device

setDescriptionFile()
Short description

Sets the path to the ".sopas" file to use as description for the device to communicate with. A ".sopas" file can be created using SOPAS ET and store a project. Take care that the file needs to be created for the correct device variant. The setDeviceSelector()-function can be used to select a device if there are multiple devices in the ".sopas"-file.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

filePath

STRING

The path to the file to use as description for the device to communicate with

Sample
Command.Client.setDescriptionFile(handle, "resources/myFile.sopas")
setDeviceSelector()
Short description

Sets the device selector which should used to define which description to loaded from the ".sopas" description file. Can be left empty (as per default) to load the first description in the file or if there is just one single description in the file. The selector can be a device type name, device variant and/or the location name. Not used selectors could be set to empty string.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

deviceName

STRING

The name of the device to load from the description file. Could be empty string.

deviceVariant

STRING

The variant of the device to load from the description file. Could be empty string.

locationName

STRING

The location name of the device to load from the description file. Could be empty string.

Sample
Command.Client.setDeviceSelector(handle, "Lector652 Flex")
setProtocol()
Short description

Sets the protocol to use to the device. Default is "CoLa A".

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

protocol

ENUM ProtocolType

The protocol to use to the device.

Sample
Command.Client.setProtocol(handle, "COLA_A")
setRequestTimeout()
Short description

Sets the timeout in milliseconds for every request like read, write, invokeMethod, enableChangeListener/disableChangeListener and also backup/restore requests. Default is 30 seconds. Maximum is 65 seconds. The value can also be changed on the fly when the client is open. Only for backup/restore requests the timeout needs to be set before callin the open function.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

timoutMs

INT

The timeout in ms for every request. Max. 65 seconds.

Sample
Command.Client.setRequestTimeout(handle, 5000)
write()
Short description

Writes a value to a parameter of the connected device. The value can retrieved by reading first or using the createNode function.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

varName

STRING

The communication name of the variable

paramNode

CONST_OBJECT Parameters.Node

The node value to write

Return values
Name Type Description

success

BOOL

True if successfully written. False if parameter was not written.

Sample
local bSucces = Command.Client.write(handle, "theParameterName", paramNode)

Events

OnChanged
Short description

Event which is notified if any change listener received a change of a variable. If the event has values, they are provided as a "Parameters.Node" object.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventName

STRING

The name of the variable or event which has changed

paramNode

OBJECT Parameters.Node

The event value if the event has arguments

Command.Methods

Short description

Provides functionality to implement CoLa command methods of the device.

Overview

Functions

add()
Short description

Adds a new method implementation. Every method could only be added once in the system. The added function callback is called if the method is executed. The callback gets the method parameters and also a prepared return parameter objects (if defined any) as function parameters. The callback should set the values on the return parameter object and should return it if successfully executed. If the callback does not return the return value object, there is an error thrown on the CoLa command interface with number 0x14 (internal error) The method parameters and return values are each in a "Parameters.Node"-object. See the sample code for how a callback implementation looks like.

Parameters
Name Type Description

handle

HANDLE

The instance handle of Command.Methods

commandName

STRING

The command method name as served on CoLa interface

funcCallback

STRING

The function name which implements the method. Needs to have a specific signature, read more about in the function documentation.

Return values
Name Type Description

success

BOOL

True if added successfully. False if method does not exist or is already added by someone in the system.

Sample
function callback(paramNode, resultNode)
  -- get values from "paramNode" using Parameters.Node-functions
  -- set values on "resultNode" using Parameters.Node-functions
  -- if successful return the resultNode
  return resultNode
end
local bSuccess = Command.Methods.add(handle, "MyMethodName", callback)
create()
Short description

Creates a new method handling instance. The methods stay implement as long as this instance exists.

Return values
Name Type Description

handle

HANDLE

The new Command.Methods instance

Sample
handle = Command.Methods.create()

Connector

Short description

Contains CROWNs to access connectors at the device

Overview

Connector.DigitalIn

Short description

Provides functionality to control a digital input port at the device

Functions

create()
Short description

Creates a digital input port with the given name if exists and not already in use.

Parameters
Name Type Description

portName

ENUM DigitalInPorts

The devices identifier of the digital input port (e.g. DI1)

Return values
Name Type Description

handle

HANDLE

Unique handle for the port. Nil if not available or already in use.

Sample
handle = Connector.DigitalIn.create("DI1")
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

get()
Short description

Returns the current activation state of the specified input port.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the port.

Return values
Name Type Description

isActive

BOOL

True if input port is active, false if inactive.

Sample
local isActive = Connector.DigitalIn.get(handle)
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

setDebounceValue()
Short description

The debounce value to use for the debounce mode. Meaning of the value is dependent on the DebounceMode which is set. Default is zero which means no debouncing at all.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the port

newValue

INT

The debounce value to use. Is dependent on the DebounceMode which is set.

Sample
Connector.DigitalIn.setDebounceValue(handle, 10)
setLogic()
Short description

Sets the pin inversion of the port to ACTIVE_HIGH or ACTIVE_LOW. Default is ACTIVE_HIGH.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the port

newLogic

ENUM SignalLogic

ACTIVE_HIGH or ACTIVE_LOW

Sample
Connector.DigitalIn.setLogic(handle, "ACTIVE_HIGH")

Events

OnChange
Short description

This event is triggered whenever the input port changes its state. The new state is provided as parameter. If there is a new registration done on this event, the current state is also thrown. Please note that there might be state changes missed by the implementation in overload situations and the same state might be notified twice.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the port

newState

BOOL

The state of the level signal

Sample
Connector.DigitalIn.register(handle, "OnChange", "MyApp.handleChange")
OnChangeStamped
Short description

This event is triggered whenever the input port changes its state. The new state and exact increment and timestamp are provided as parameter. If there is a new registration done on this event, the current state is also thrown. Please note that there might be state changes missed by the implementation in overload situations and the same state might be notified twice.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the port

newState

BOOL

The state of the level signal

timeOfStateChange

INT

The timestamp in microseconds the state of the signal changed

incrementOfStateChange

INT

The increment stamp in ticks the state of the signal changed

Sample
Connector.DigitalIn.register(handle, "OnChangeStamped", "MyApp.handleChangeStamped")

Connector.DigitalOut

Short description

Provides functionality to control a digital output port at the device

Functions

create()
Short description

Creates a digital output port with the given name if exists and not already in use.

Parameters
Name Type Description

portName

ENUM DigitalOutPorts

The devices identifier of the digital output port (e.g. DO1)

Return values
Name Type Description

handle

HANDLE

Unique handle for the port. Nil if not available or already in use.

Sample
handle = Connector.DigitalOut.create("DO1")
set()
Short description

Sets the port state to the given value.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the port

newState

BOOL

The new state of the level signal

Sample
Connector.DigitalOut.set(handle, level)
setActivationMode()
Short description

The activation mode to set for this port so that the port is automatically reset after a given time. Default is time based.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the port

value

ENUM ActivationMode

The activation mode to use

Sample
Connector.DigitalOut.setActivationMode(handle, "TIME_MS")
setActivationValue()
Short description

The activation value to set for this port. Meaning of the value is dependent on the ActivationMode which is set. Default is zero which means not automatically reset.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the port

value

INT

The activation value to use. Is dependent on the ActivationMode which is set.

Sample
Connector.DigitalOut.setActivationValue(handle, 100)
setLogic()
Short description

Sets the pin inversion of the port to ACTIVE_HIGH or ACTIVE_LOW. Default is ACTIVE_HIGH.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the port

value

ENUM SignalLogic

ACTIVE_HIGH or ACTIVE_LOW

Sample
Connector.DigitalOut.setLogic(handle, "ACTIVE_HIGH")

Connector.DigitalOut.DelayedEvents

Short description

Provides functionality to control the digital outputs with high precision and a defined delay in time or distance. Output events will be added to a queue so that several events can be added before the first event is activated. The events have both a start value (when the event should start) and a duration value (the time or distance to hold the output active).

Functions

add()
Short description

Add a delayed event to the queue. The units of the start and duration values are specified when enabling delayed events for an output.

Parameters
Name Type Description

handle

HANDLE

The instance to use.

startValue

INT

Output activation start value in configured unit.

durationValue

INT

Output duration value in configured unit.

Return values
Name Type Description

success

BOOL

Returns true if the add was successful, otherwise false.

status

ENUM StatusCode

Result code.

Sample
success, status = Connector.DigitalOut.DelayedEvents.add(handle, startValue, durationValue)
clear()
Short description

Removes all events in the queue that have not yet been activated.

Parameters
Name Type Description

handle

HANDLE

The instance to use.

Return values
Name Type Description

success

BOOL

Returns true if the queue was successfully cleared, otherwise false.

Sample
success = Connector.DigitalOut.DelayedEvents.clear(handle)
create()
Short description

Creates a DelayedEvents instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance.

Sample
handle = Connector.DigitalOut.DelayedEvents.create()
disable()
Short description

Disables delayed events and removes all events that have not yet been activated. After disabling delayed events, the queue can be reconfigured with enable().

Parameters
Name Type Description

handle

HANDLE

The instance to use.

Return values
Name Type Description

success

BOOL

Returns true if disable was successful, otherwise false.

Sample
success = Connector.DigitalOut.DelayedEvents.disable(handle)
enable()
Short description

Enable delayed events for a digital output. Configure which output to enable for delayed events, which units to use for start and duration, and a maximum duration timeout. If an event reaches the maximum timeout time before the event duration is complete, it will be automatically deactivated and removed from the queue.

Parameters
Name Type Description

handle

HANDLE

The instance to use.

connectorHandle

HANDLE

Output pin to use.

startUnit

ENUM MeasurementUnit

The unit for event start values.

durationUnit

ENUM MeasurementUnit

The unit for event duration values.

maxDurationTimeout

INT

Maximum event duration time (in microseconds).

Return values
Name Type Description

success

BOOL

Returns true if successful, otherwise false.

Sample
success = Connector.DigitalOut.DelayedEvents.enable(handle, do4, "TIME_US", "INCREMENT_TICK", 1000000)

Connector.Increment

Short description

Represents the input/output pins of an INC plug.

Overview

Functions

create()
Short description

Creates a new instance.

Parameters
Name Type Description

portName

ENUM IncrementPortConnectors

The devices identifier of the connector (e.g. INC1)

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
handle = Connector.Increment.create("INC1")

Container

Short description

An associative container storing all kind of CROWN datatypes (like objects, strings, booleans etc.). Each item in the container is identified using a string name as key. One item in the container can represent both a single value as well as vectors. Adding to the container is done using a general purpose add()-function. For retrieval of items there are more options: There is a general purpose get() function that provides the item, but type checking of the obtained instance must be done by the user. There is a set of typed functions for retrieving items from the container which check that the item to be retrieved also has the expected type. Internally, the implementation uses a hash map for fast value access. The order of adding items is not relevant. Access to the container is thread-safe.

Functions

add()
Short description

Adds an item to the container. The item can be a float, integer, bool, string or any object. Only works with non-const objects, for const-objects use the "addConst"-function. If an item with the same name already exists in the container, the function returns false. The container itself cannot be added as item.

Parameters
Name Type Description

container

OBJECT Container

Container instance.

name

STRING

Name of the item. Must not be empty.

item

AUTO

Item to add to the container. Nil value is not possible.

itemType

ENUM ItemTypes

Can be specified to set explicitly the type name for the item which should be added. An attempt is made to convert the item to this target type.

Return values
Name Type Description

success

BOOL

Returns true if successfully added. False if item already exists or item type does not match.

addConst()
Short description

Adds a const item to the container. The item can be a float, integer, bool, string or any object. Objects can be non-const or const and are forced to be const inside the container. If an item with the same name already exists in the container, the function returns false. The container itself cannot be added as item.

Parameters
Name Type Description

container

OBJECT Container

Container instance.

name

STRING

Name of the item. Must not be empty.

item

CONST_AUTO

Item to add to the container. Nil value is not possible.

itemType

ENUM ItemTypes

Can be specified to set explicitly the type name for the item which should be added. An attempt is made to convert the item to this target type.

Return values
Name Type Description

success

BOOL

Returns true if successfully added. False if item already exists or item type does not match.

clear()
Short description

Clears the entire container.

Parameters
Name Type Description

container

OBJECT Container

Container instance.

create()
Short description

Creates a new container.

Return values
Name Type Description

container

OBJECT Container

The new container.

exists()
Short description

Checks if an item with the provided key string exists in the container.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

name

STRING

Name of the item to check.

Return values
Name Type Description

result

BOOL

True if the Container contains an item with the provided key name.

get()
Short description

Get any item from the container. No type-checking is done on the item to get, it can be an integer, float, bool, object etc., or a vector of such types. To get a const-object value use the "getConst"-function. It is up to the user to make sure that the returned value is of the correct type before further usage.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

name

STRING

Name of the item.

itemType

ENUM ItemTypes

Can be specified to explicitly get the item only if the type matches. If the item type does not match, nil is returned.

Return values
Name Type Description

item

AUTO

Returns item if retrieval was successful, otherwise nil.

getConst()
Short description

Get any item from the container as const. No type-checking is done on the item to get, it can be an integer, float, bool, object etc., or a vector of such types. Objects can be non-const or const and are always returned as const object. It is up to the user to make sure that the returned value is of the correct type before further usage.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

name

STRING

Name of the item.

itemType

ENUM ItemTypes

Can be specified to explicitly get the item only if the type matches. If the item type does not match, nil is returned.

Return values
Name Type Description

item

CONST_AUTO

Returns item if retrieval was successful, otherwise nil.

getSize()
Short description

Returns the number of items in the container.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

Return values
Name Type Description

size

INT

Number of items in the container.

getType()
Short description

Returns a the enum string type definition of the underlying type of the item.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

name

STRING

Name of the item to check.

Return values
Name Type Description

type

ENUM ItemTypes

The string describing the type. Will be nil if the key name is not found.

isEmpty()
Short description

Checks if the container is empty.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

Return values
Name Type Description

result

BOOL

True if the container is empty.

isSingle()
Short description

Checks if the item with the provided key string is a single instance, as opposed to a vector-valued instance.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

name

STRING

Name of the item to check.

Return values
Name Type Description

result

BOOL

True if the item with the provided key name is a single instance. False if it is a vector valued instance or if the key name does not exist.

isType()
Short description

Checks if the item with the specified key string is of the specified type.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

name

STRING

Name of the item to check.

type

ENUM ItemTypes

The type name to compare against.

Return values
Name Type Description

result

BOOL

True if the item with the provided key name is of the queried type. False if it the type is wrong. Nil if the key name does not exist.

isVector()
Short description

Checks if the item with the provided key string is a vector-valued instance, as opposed to a single instance.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

name

STRING

Name of the item to check.

Return values
Name Type Description

result

BOOL

True if the item with the provided key name is a vector-valued instance. False if it is a single instance or if the key name does not exist.

list()
Short description

Gets a list of all key names in the container in alphabetical order.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

Return values
Name Type Description

item

STRING

A string vector with the names of all items in the container in alphabetical order.

remove()
Short description

Removes an item from the container. If there is no item with the provided key string, nothing is done and false is returned.

Parameters
Name Type Description

container

OBJECT Container

Container instance.

name

STRING

Name of the item to remove.

Return values
Name Type Description

success

BOOL

Returns true if item existed and was removed, false if item did not exist.

toString()
Short description

Returns a string representation of the content of the container.

Parameters
Name Type Description

container

CONST_OBJECT Container

Container instance.

Return values
Name Type Description

description

STRING

User-friendly description of the container.

update()
Short description

Updates an existing item in the container. The item can be a float, integer, bool, string or any object. Only works with non-const objects, for const-objects use the "updateConst"-function. If an item with the name does not exist in the container, the function returns false. If the existing item has a different type than specified, the function returns false. The container itself cannot be set as item.

Parameters
Name Type Description

container

OBJECT Container

Container instance.

name

STRING

Name of the item. Must not be empty.

item

AUTO

Item to update in the container. Nil value is not possible.

itemType

ENUM ItemTypes

Can be specified to set explicitly the type name for the item which should be updated. An attempt is made to convert the item to this target type.

Return values
Name Type Description

success

BOOL

Returns true if successfully updated. False if item does not exist or item type does not match.

updateConst()
Short description

Updates an existing const item in the container. The item can be a float, integer, bool, string or any object. Objects can be non-const or const, and are forced to be const inside the container. If an item with the name does not exist in the container, the function returns false. If the existing item has a different type than specified, the function returns false. The container itself cannot be set as item.

Parameters
Name Type Description

container

OBJECT Container

Container instance.

name

STRING

Name of the item. Must not be empty.

item

CONST_AUTO

Item to update in the container. Nil value is not possible.

itemType

ENUM ItemTypes

Can be specified to set explicitly the type name for the item which should be updated. An attempt is made to convert the item to this target type.

Return values
Name Type Description

success

BOOL

Returns true if successfully updated. False if item does not exist or item type does not match.

DateTime

Short description

Provides functions to get date and time as well as conversion routines.

Functions

calcDayOfWeek()
Short description

Calculates the day of the week in the current time zone as integer (Sunday=0, Monday=1, Tuesday=2, …​, Saturday=6. The returned value can be used as key to a table mapping the values to strings if desired (see the example). The return value is a number because of different country-local requirements: In some countries, Sunday is the first day of the week, in some others it’s the Monday. Also, the names of the days may differ. The convention Sunday=0, Monday=1 is derived from the standard C library convention of day of week numbers. For invalid Unix time input the function returns nil.

Parameters
Name Type Description

unixUTCTime

INT

The Unix input time

Return values
Name Type Description

dayNr

INT

Number of the current day of week or nil in case of invalid input

Sample
local dayStrEnglish = {} -- English day names
dayStrEnglish[0] = "Sun"
dayStrEnglish[1] = "Mon"
dayStrEnglish[2] = "Tue"
dayStrEnglish[3] = "Wed"
dayStrEnglish[4] = "Thu"
dayStrEnglish[5] = "Fri"
dayStrEnglish[6] = "Sat"
dayStrGerman = {} -- German day names
dayStrGerman[0] = "So"
dayStrGerman[1] = "Mo"
dayStrGerman[2] = "Di"
dayStrGerman[3] = "Mi"
dayStrGerman[4] = "Do"
dayStrGerman[5] = "Fr"
dayStrGerman[6] = "Sa"
local currentDayAsNumber = DateTime.calcDayOfWeek(DateTime.getUnixTime())
local currentDayInEnglish = dayStrEnglish[currentDayAsNumber]
local currentDayInGerman  = dayStrGerman[currentDayAsNumber]
calcLocalFromUTC()
Short description

Converts Unix time to local time and generates a string like the one returned by getDateTime(). This function is deprecated, please use formatUnixTime() instead.

Parameters
Name Type Description

unixUTCTime

INT

The Unix time

Return values
Name Type Description

dateTime

STRING

Format: "Jan..Dec dd yyyy hh:mm:ss" or nil for invalid Unix time input

Sample
local dateTime = DateTime.calcLocalFromUTC(DateTime.getUnixTime() + 10) -- Date and Time 10 seconds in the future
convertTimestamp()
Short description

Returns the individual parts (day, month, year, hour, minute, second, millisecond) of the time which is calculated from the input timestamp in milliseconds since bootup.

Parameters
Name Type Description

timestamp

INT

The input timestamp

asUTC

BOOL

True to return UTC, false to convert to local time. Defaults to false (local time).

Return values
Name Type Description

day

INT

Day

month

INT

Month

year

INT

Year

hour

INT

Hour

minute

INT

Minute

second

INT

Second

millisecond

INT

Millisecond

Sample
local day, month, year, hour, minute, second, millisecond = DateTime.convertTimestamp(DateTime.getTimestamp())
convertUnixTime()
Short description

Returns the individual parts (day, month, year, hour, minute, second) of an input Unix time.

Parameters
Name Type Description

unixTime

INT

The Unix time

asUTC

BOOL

True to return UTC, false to convert to local time. Defaults to false (local time).

Return values
Name Type Description

day

INT

Day

month

INT

Month

year

INT

Year

hour

INT

Hour

minute

INT

Minute

second

INT

Second

Sample
local day, month, year, hour, minute, second = DateTime.convertUnixTime(DateTime.getUnixTime())
create()
Short description

Returns the current date and time as DateTime object. Only has valid time if the device supports it, otherwise time since bootup.

Return values
Name Type Description

dateTime

OBJECT DateTime

The current date and time as DateTime object

Sample
local now = DateTime.create()
createFromTimestamp()
Short description

Returns the DateTime object which corresponds to the input timestamp in milliseconds since bootup.

Parameters
Name Type Description

timestamp

INT

The input timestamp

Return values
Name Type Description

dateTime

OBJECT DateTime

DateTime object which corresponds to the input timestamp

Sample
local now = DateTime.createFromTimestamp(DateTime.getTimestamp())
local bootup = DateTime.createFromTimestamp(0)
createFromUnixTime()
Short description

Returns the DateTime object which corresponds to the input Unix time (number of seconds since the "epoch" (Jan 1, 1970) in UTC) Milliseconds are set to 0.

Parameters
Name Type Description

unixTime

INT

The Unix time

Return values
Name Type Description

dateTime

OBJECT DateTime

DateTime object which corresponds to the input Unix time

Sample
local now = DateTime.createFromUnixTime(DateTime.getUnixTime())
local epoch = DateTime.createFromUnixTime(0)
formatTimestamp()
Short description

Generates a string like the one returned by getDateTime() for the time which is calculated from the input timestamp in milliseconds since bootup.

Parameters
Name Type Description

timestamp

INT

The input timestamp

asUTC

BOOL

True to return UTC, false to convert to local time. Defaults to false (local time).

Return values
Name Type Description

dateTime

STRING

Format: "Jan..Dec dd yyyy hh:mm:ss.msecs" or nil for invalid Unix time input

Sample
local localTime  = DateTime.formatTimestamp(DateTime.getTimestamp())
local bootupTime = DateTime.formatTimestamp(0)
formatUnixTime()
Short description

Generates a string like the one returned by getDateTime() for the input Unix time.

Parameters
Name Type Description

unixTime

INT

The Unix time

asUTC

BOOL

True to return UTC, false to convert to local time. Defaults to false (local time).

Return values
Name Type Description

dateTime

STRING

Format: "Jan..Dec dd yyyy hh:mm:ss" or nil for invalid Unix time input

Sample
local localTime = DateTime.formatUnixTime(DateTime.getUnixTime(), false)
local epoch = DateTime.formatUnixTime(0, true)
getDate()
Short description

Returns the current date in format "Jan..Dec dd yyyy". Only has valid time if the device supports it, otherwise time since bootup.

Return values
Name Type Description

date

STRING

Format: "Jan..Dec dd yyyy"

Sample
local time = DateTime.getDate()
getDateTime()
Short description

Returns the current date plus time in format "Jan..Dec dd yyyy hh:mm:ss.msecs. This is the same like concatenating the strings returned by getDate and getTime with a space delimiter, but a call to getDateTime is atomic and also works when date/time overflows whereas two calls to getDate and getTime are not guaranteed to fit together because some time could pass by between the calls.

Return values
Name Type Description

datetime

STRING

Format: "Jan..Dec dd yyyy hh:mm:ss.msecs"

Sample
local dateTime = DateTime.getDateTime()
getDateTimeValuesLocal()
Short description

Returns the individual parts (day, month, year, hour, minute, second, millisecond) of the system time in local time.

Return values
Name Type Description

day

INT

Day

month

INT

Month

year

INT

Year

hour

INT

Hour

minute

INT

Minute

second

INT

Second

millisecond

INT

Millisecond

Sample
local day, month, year, hour, minute, second, millisecond = DateTime.getDateTimeValuesLocal()
getDateTimeValuesUTC()
Short description

Returns the individual parts (day, month, year, hour, minute, second, millisecond) of the system time in UTC (Coordinated Universal Time).

Return values
Name Type Description

day

INT

Day

month

INT

Month

year

INT

Year

hour

INT

Hour

minute

INT

Minute

second

INT

Second

millisecond

INT

Millisecond

Sample
local day, month, year, hour, minute, second, millisecond = DateTime.getDateTimeValuesUTC()
getTime()
Short description

Returns the current time in format "hh:mm:ss.msecs". Only has valid time if the device supports it, otherwise time since bootup.

Return values
Name Type Description

time

STRING

Format: "hh:mm:ss.msecs"

Sample
local time = DateTime.getTime()
getTimeZone()
Short description

Returns the currently set time zone in IANA tz database format. The function queries the underlying operating system for the current time zone and returns the corresponding string. When the time zone is not available, or could not be translated into the IANA format, or is not implemented on the operating system, an empty string is returned. When using DateTime.setTimeZone(), the returned string of this function may be different to one set before because the IANA format allows various synonyms for time zones. But it is assured that the returned string describes a time zone that is a synonym to the last one passed to setTimeZone() even if it is different. For example, the result may be "Europe/Vienna" even when "Europe/Berlin" was passed to setTimeZone() because both cities are located in the same time zone.

Return values
Name Type Description

timeZone

STRING

The currently set time zone or an empty string if getting is not possible

Sample
local currentZone = DateTime.getTimeZone()
getTimestamp()
Short description

Returns the system timestamp in milliseconds since bootup.

Return values
Name Type Description

timestamp

INT

Stamp in milliseconds

Sample
local timestamp = DateTime.getTimestamp()
getTimestampMicroseconds()
Short description

Returns the system timestamp in microseconds since bootup.

Return values
Name Type Description

timestamp

INT

Stamp in microseconds

Sample
local timestamp = DateTime.getTimestampMicroseconds()
getUnixTime()
Short description

Returns the current time as number of seconds since the "epoch" (Jan 1, 1970) in UTC (Coordinated Universal Time). The returned value can directly be used to perform arithmetic and calculate time values.

Return values
Name Type Description

unixtime

INT

The Unix time

Sample
local unixTime = DateTime.getUnixTime()
isTimeSet()
Short description

Returns whether the system time has been set (by NTP or some other service) since bootup, so the getDate/Time() calls deliver reliable results.

Return values
Name Type Description

isSet

BOOL

true when the system date has been set minimum once since bootup

Sample
local timeSetSinceBootUp = DateTime.isTimeSet()
setDateTime()
Short description

Sets the system time in either UTC (Coordinated Universal Time) or local time. Attention: The system behaviour might be affected if changing the time too often, so use with care. The usage of NTPClient is generally more recommended. Please also take care when setting local time (not UTC) to an interval where daylight saving time changes to non daylight saving time (mostly in autumn). The results when setting to that time interval are undefined, because the time interval repeats a second time during the transition (for example 2:59:58, 2:59:59, 2:00:00, 2:00:01, …​, 2:59:58, 2:59:59, 3:00:00) so the time values are ambiguous.

Parameters
Name Type Description

year

INT

Year to set, range: 1970..2037

month

INT

Month to set, range: 1..12

day

INT

Day to set, range: 1..31

hour

INT

Hour to set, range: 0..23

minute

INT

Minute to set, range: 0..59

second

INT

Second to set, range: 0..59

asUTC

BOOL

True to set in UTC, false to set in local time. Defaults to false (local time).

Return values
Name Type Description

success

BOOL

If true, the time was set successfully

Sample
DateTime.setDateTime(2016, 1, 15, 14, 30, 10, true)
setTimeZone()
Short description

Sets the time zone of the system. The time zone is encoded in the IANA tz database format. A current list can be looked up from http://en.wikipedia.org/wiki/List_of_tz_database_time_zones. Time zones do not change the system clock which always runs in UTC, but they change how dates and times are interpreted in a locally dependent way. The functions getDateTime(), getDate() and getTime() will return different values when the time zone is overwritten. Note that time zones are subject to political changes, so in the future, time zones of some countries may change even if that is rather unlikely. Not each operating system supports each time zone. So, always check the return code of this function. If the call is unsuccessful, you may need another compatible time zone name or you will need to update your device firmware to fit to the new zones. The Windows version of this function uses a mapping provided by unicode.org, browsable under http://www.unicode.org/cldr/charts/latest/supplemental/zone_tzid.html, so the IANA names can be universally used for each underlying operating system.

Parameters
Name Type Description

timeZoneString

STRING

The time zone string in IANA tz database format

Return values
Name Type Description

success

BOOL

If true, the time zone was set successfully

Sample
local result = DateTime.setTimeZone("America/New_York")
toString()
Short description

Gets a user-friendly string description of a DateTime object (UTC time according to the ISO 8601 time representation).

Parameters
Name Type Description

dateTime

CONST_OBJECT DateTime

The DateTime object.

Return values
Name Type Description

str

STRING

User-friendly description of a DateTime object.

Sample
str = DateTime.toString(dateTime)

DigitalLogic

Short description

Contains DigitalLogic elements to be used in Control Flows.

DigitalLogic.Delay

Short description

Delays incoming signals for a given delay.

Functions

create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
handle = DigitalLogic.Delay.create()
delay()
Short description

Starts a delay with a millisecond or mm resolution.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

signal

BOOL

The state of the level/Dirac signal to delay

Return values
Name Type Description

delayedSignal

BOOL

The state of the delayed level/Dirac signal

Sample
delayedSignal=DigitalLogic.Delay.delay(handle, signal)
highAccuracyDelay()
Short description

Starts a delay with a microsecond or increment tick resolution.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

signal

BOOL

The state of the level signal to delay

Return values
Name Type Description

delayedSignal

BOOL

The state of the delayed level signal

Sample
delayedSignal=DigitalLogic.Delay.highAccuracyDelay(handle, signal)
setDelayDistance()
Short description

Distance in mm or increment ticks. Resolution depends on the used function (delay or highAccuracyDelay).

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

delayDistance

INT

Distance in mm or increment ticks. Resolution depends on the used function (delay or highAccuracyDelay).

Sample
DigitalLogic.Delay.setDelayDistance(handle, 100)
setDelayTime()
Short description

Time in milliseconds or microseconds for the delay. Resolution depends on the used delay function delay or highAccuracyDelay.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

delayTime

INT

Time in milliseconds or microseconds. Resolution depends on the used function (delay or highAccuracyDelay).

Sample
DigitalLogic.Delay.setDelayTime(handle, 10)
setMaxQueueSize()
Short description

Maximum number of queued signals (0: unlimited). Affects only delay, not highAccuracyDelay.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

maxQueueSize

INT

Maximum number of queued signals (0: unlimited)

Sample
DigitalLogic.Delay.setMaxQueueSize(handle, 100)

DigitalLogic.EdgeDetector

Short description

Detects edges in a level signal and generates Dirac signals for the falling and rising edge.

Overview

Functions

create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
handle = DigitalLogic.EdgeDetector.create()
detect()
Short description

Detects edges in a level based signal and generates Dirac signals.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

level

BOOL

The state of the level signal

Return values
Name Type Description

risingEdge

BOOL

Creates a Dirac signal if a rising edge is detected in the level signal.

fallingEdge

BOOL

Creates a Dirac signal if a falling edge is detected in the level signal.

Sample
risingEdge, fallingEdge = DigitalLogic.EdgeDetector.detect(handle, level)

DigitalLogic.Gate

Short description

Logical gate functions implemented in hardware or software.

Functions

and()
Short description

Combine the input signals with a logical AND.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

levelA

BOOL

The state of the first signal

levelB

BOOL

The state of the second signal

levelC

BOOL

The state of the third optional signal

levelD

BOOL

The state of the fourth optional signal

Return values
Name Type Description

level

BOOL

Resulting output signal of the logical AND, only if state changed.

Sample
level = DigitalLogic.Gate.and(handle, levelA, levelB, levelC, levelD)
create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
handle = DigitalLogic.Gate.create()
nand()
Short description

Combine the input signals with a logical NAND.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

levelA

BOOL

The state of the first signal

levelB

BOOL

The state of the second signal

levelC

BOOL

The state of the third optional signal

levelD

BOOL

The state of the fourth optional signal

Return values
Name Type Description

level

BOOL

Resulting output signal of the logical NAND, only if state changed.

Sample
level = DigitalLogic.Gate.nand(handle, levelA, levelB, levelC, levelD)
nor()
Short description

Combine the input signals with a logical NOR.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

levelA

BOOL

The state of the first signal

levelB

BOOL

The state of the second signal

levelC

BOOL

The state of the third optional signal

levelD

BOOL

The state of the fourth optional signal

Return values
Name Type Description

level

BOOL

Resulting output signal of the logical NOR, only if state changed.

Sample
level = DigitalLogic.Gate.nor(handle, levelA, levelB, levelC, levelD)
not()
Short description

Invert the input signal with a logical NOT.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

levelA

BOOL

The state of the input signal

Return values
Name Type Description

level

BOOL

Resulting output signal of the logical NOT, only if state changed.

Sample
level = DigitalLogic.Gate.not(handle, levelA)
or()
Short description

Combine the input signals with a logical OR.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

levelA

BOOL

The state of the first signal

levelB

BOOL

The state of the second signal

levelC

BOOL

The state of the third optional signal

levelD

BOOL

The state of the fourth optional signal

Return values
Name Type Description

level

BOOL

Resulting output signal of the logical OR, only if state changed.

Sample
level = DigitalLogic.Gate.or(handle, levelA, levelB, levelC, levelD)
setAffinity()
Short description

Changes the affinity of the control flow block

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

value

ENUM Affinity

Affinity of the gate block.

Sample
DigitalLogic.Gate.setAffinity(handle, newAffinity)
xnor()
Short description

Combine the input signals with a logical XNOR. If only one of the input signals is high, the output is low. Attention: Also if three of the input signals are high, the output is still high (this is different than the 3-way xnor definition).

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

levelA

BOOL

The state of the first signal

levelB

BOOL

The state of the second signal

levelC

BOOL

The state of the third optional signal

levelD

BOOL

The state of the fourth optional signal

Return values
Name Type Description

level

BOOL

Resulting output signal of the logical XNOR, only if state changed.

Sample
level = DigitalLogic.Gate.xnor(handle, levelA, levelB, levelC, levelD)
xor()
Short description

Combine the input signals with a logical XOR. If only one of the input signals is high, the output is high. Attention: Also if three of the input signals are high, the output is still low (this is different than the 3-way xor definition).

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

levelA

BOOL

The state of the first signal

levelB

BOOL

The state of the second signal

levelC

BOOL

The state of the third optional signal

levelD

BOOL

The state of the fourth optional signal

Return values
Name Type Description

level

BOOL

Resulting output signal of the logical XOR, only if state changed.

Sample
level = DigitalLogic.Gate.xor(handle, levelA, levelB, levelC, levelD)

DigitalLogic.TFlipFlop

Short description

Toggle a level signal from high to low or vice versa on each incoming Dirac signal.

Overview

Functions

create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
handle = DigitalLogic.TFlipFlop.create()
toggle()
Short description

Toggle a level signal from high to low or vice versa on each incoming Dirac signal. The default state is low.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

signal

BOOL

The incoming Dirac signal

Return values
Name Type Description

level

BOOL

The resulting level signal

Sample
level = DigitalLogic.TFlipFlop.toggle(handle, signal)

Encoder

Functions

create()
Short description

Creates an encoder with the given name if exists and not already in use.

Parameters
Name Type Description

encSrc

ENUM EncoderIncrementSources

The devices identifier of the encoder (e.g. ENC1)

Return values
Name Type Description

handle

HANDLE

Unique handle for the encoder. Nil if not available or already in use.

Sample
handle = Encoder.create("ENC1")
getCurrentIncrement()
Short description

Retrieve the current increment count value and corresponding timestamp.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the encoder object.

Return values
Name Type Description

increment

INT

Current increment value.

timestamp

INT

Current timestamp in microseconds.

Sample
local incr, timestamp = Encoder.getCurrentIncrement()
getDirection()
Short description

Retrieve the current direction (forward/backward).

Parameters
Name Type Description

handle

HANDLE

The instance handle of the encoder object.

Return values
Name Type Description

direction

ENUM Direction

Current direction (forward/backward).

Sample
local direction = Encoder.getDirection()
getTicksPerSecond()
Short description

Retrieve the current speed value (increment/sec).

Parameters
Name Type Description

handle

HANDLE

The instance handle of the encoder object.

Return values
Name Type Description

ticksPerSecond

INT

Current ticks per second value.

Sample
local ticksPerSecond = Encoder.getTicksPerSecond()
setCountMode()
Short description

Select how increments will be counted

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

mode

ENUM DecoderCountMode

The decoder count mode to set

Sample
Encoder.setCountMode(handle, mode)
setSource()
Short description

Sets source for the increment decoder input. Could be either an increment connector (external) or an encoder generator (internal) which could be used for fixed speed.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

sourceHandle

HANDLE

Handle of the connected input source.

Sample
Encoder.setSource(handle, sourceHandle)

Engine

Short description

Provides functionality to control the AppEngine of the device and use the AppEngine framework.

Functions

getCrownAsXML()
Short description

Returns the manifest xml snippet of the specified CROWN as xml string. Sub-CROWNs are NOT included. Output string starts and ends with the "crown" xml tag. The name of the crown is only the sub-crown name and NOT the full qualified crown name. E.g. requested crown name is "NameA.NameB.NameC", output xml crown name is only "NameC".

Parameters
Name Type Description

crownName

STRING

The full CROWN name to return the manifest

Return values
Name Type Description

manifestXml

STRING

The manifest xml snippet of the CROWN or nil if CROWN does not exist

Sample
local manifestString = Engine.getCrownAsXML("TheCrownName")
getCrowns()
Short description

Returns the list of all crowns which are available in the engine as vector sorted alphabetically. The domain filter like 'ctrl-flow' can be specified, to only return CROWNs which are relevant for the specified domain. The CROWN can also be relevant if there is just one function or event specified as include. Available domain filters: - ctrl-flow - data-flow - script - remote - java

Parameters
Name Type Description

domainFilter

STRING

If specified, only returns the crowns which have an include specified to the domain like 'ctrl-flow' and no exclude is defined to it. See manifest scheme for all available include-domains.

Return values
Name Type Description

crownVector

STRING

The sorted vector for all full-qualified crown names

Sample
local crownList = Engine.getCrowns()
getCurrentAppName()
Short description

Get the name of the app from which this function is called.

Return values
Name Type Description

name

STRING

The name of the app or nil if app context is not available.

Sample
local name = Engine.getCurrentAppName()
getCurrentAppVersion()
Short description

Get the version of the app from which this function is called.

Return values
Name Type Description

version

STRING

The version of the app or nil if app context is not available.

Sample
local version = Engine.getCurrentAppVersion()
getEnumValues()
Short description

Returns all enum values of an enum defined in the manifest as a vector sorted alphabetically.

Parameters
Name Type Description

enumName

STRING

The full CROWN enum name to return its values

Return values
Name Type Description

enumVals

STRING

The sorted vector of enum values or nil if enum does not exist

Sample
local enumValTable = Engine.getEnumValues("Log.Level")
getFirmwareVersion()
Short description

Returns the device firmware version of this engine

Return values
Name Type Description

firmwareVersion

STRING

The device firmware version of this engine

getPartNumber()
Short description

Returns the device part number of this engine

Return values
Name Type Description

partNumber

STRING

The device part number of this engine

getSerialNumber()
Short description

Returns the device serial number of this engine as string

Return values
Name Type Description

serialNumber

STRING

The device serial number of this engine as string

getTypeCode()
Short description

Returns the device type code of this engine

Return values
Name Type Description

typeCode

STRING

The device type code of this engine

getTypeName()
Short description

Returns the device type name of this engine

Return values
Name Type Description

typeName

STRING

The device type name of this engine

getVersion()
Short description

Returns the AppEngine version of this device

Return values
Name Type Description

engineVersion

STRING

The AppEngine version of this device

isEmulator()
Short description

This function return true if the current engine is just an emulator engine and not a real device.

Return values
Name Type Description

isEmulator

BOOL

True if the current device is an emulator

listApps()
Short description

Returns the names of all apps currently in the engine.

Return values
Name Type Description

appList

STRING

List of app names

reboot()
Short description

Reboots the device over power cycle directly. Function will NOT return on target hardware. On the emulator the function always returns and logs a warning that reboot is not possible on emulator. This function can only be used after the "Engine.OnStarted" event has been notified to prevent endless reboot loops in global scope. Before the event the function call is ignored. During the first 30 seconds after the "Engine.OnStarted" event the reboot action keeps pending so that an endless reboot loop is prevented. Every 5 seconds there is a log that a reboot is pending, so that the app developer has time to connect and stop the apps.

Parameters
Name Type Description

reason

STRING

Optional string describing the reason for reboot

Sample
Engine.reboot("the concrete reboot reason")
reloadApps()
Short description

Reloads all applications of the AppEngine. Function will not return on target hardware and directly reloads. On the emulator the function may return. This function can be used to reset all applications and start them again like if rebooting but without full powercycle. This function can only be used after the "Engine.OnStarted" event has been notified to prevent endless reload loops in global scope.

Sample
Engine.reloadApps()

Events

OnStarted
Short description

Startup event of the application which is notified once after startup after all apps have been fully loaded. This should be used by apps which are dependent on other apps to make sure that everything is fully loaded. The event is also notified if the apps are reloaded externally or over the Engine.reloadApps function.

Sample
Script.register("Engine.OnStarted", "MyApp.handleOnStarted")

Engine.AsyncFunction

Short description

Executes a CROWN function call in an underlying separate thread. There is one thread per AsyncFunction instance. Multiple launches on an AsyncFunction instance are queued up and executed after each other. This is useful to execute functions in parallel to better benefit from multiple cores available on the target hardware. Every function launch returns a Future-handle which identifies the function call. The results can be retrieved by calling the blocking function "wait" on the Future-handle or by registering to the event "OnFinished" to retrieve the function results asynchronously.

Functions

create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
-- Create a simple async function call to a handle-based function and wait for its result:
asyncHandle = Engine.AsyncFunction.create()
asyncHandle:setFunction("Algo.function", algoHandle)
futureHandle = asyncHandle:call(p1, p2, p3)
r1, r2, r3 = futureHandle:wait()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

launch()
Short description

Starts a new call on the async handle with the specified parameters. This function directly returns a handle to an Engine.AsyncFunction.Future instance. Use this Future instance to wait for the function to be completed and get their result. Alternatively register to the "OnFinished" event to get the future objects notified there for each completed call. Multiple calls can be spawned at once. They are executed after each other.

Parameters
Name Type Description

handle

HANDLE

The instance to use

param1

AUTO

First parameter for the async function call (optional)

param2

AUTO

second parameter for the async function call (optional)

param3

AUTO

third parameter for the async function call (optional)

param4

AUTO

fourth parameter for the async function call (optional)

param5

AUTO

fifth parameter for the async function call (optional)

param6

AUTO

sixth parameter for the async function call (optional)

param7

AUTO

seventh parameter for the async function call (optional)

Return values
Name Type Description

futureHandle

HANDLE

The future handle to wait for the result of the async function call. Can be nil if there was an internal error while launching the function call or no function was set.

Sample
Engine.AsyncFunction.launch(handle, param1, param2, param3)
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

setFunction()
Short description

Sets the target CROWN function name to call in the async function call execution. If the CROWN function is handle based, the handle can be passed as second parameter to this function, so that it is automatically set as first parameter for every function call. The handle is hold as long as the AsyncFunction exists.

Parameters
Name Type Description

handle

HANDLE

The instance to use

functionName

STRING

The function name which is called by this async function instance

functionHandle

HANDLE

The optional handle which is automatically set as first parameter to every function call. The handle is held as long as the AsyncFunction exists.

Sample
-- Static function:
Engine.AsyncFunction.setFunction(handle, "Algo.function")
-- Handle based function:
Engine.AsyncFunction.setFunction(handle, "Algo.function", algoHandle)

Events

OnFinished
Short description

This event is triggered on every function async call completion. The future handle is passed as parameter to get the function result. This is useful to receive the function results asynchronously instead of using the blocking Future.wait function.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the channel

futureHandle

HANDLE

The future object identifying the function call

Sample
Engine.AsyncFunction.register(handle, "OnFinished", "handleResult")

Engine.AsyncFunction.Future

Short description

Is returned by the Engine.AsyncFunction.launch function to control the async function execution like to wait for the result. To cancel a queued up function execution, call the abandon function.

Functions

abandon()
Short description

Throws the async function execution and its result away. If the function execution is still queued, it will not be executed. If it is currently already running, the result of it will be abandoned.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Sample
Engine.AsyncFunction.Future.abandon(futureHandle)
isFailed()
Short description

If the function call is finished, this function can be used to check, if there was an error calling the function asynchronously. A fail might happen, if the function to be called was not valid (not served) or the function parameters/return values were not correct.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

isFailed

BOOL

True if the function execution was failed. False if called successfully or not finished.

Sample
isFailed = Engine.AsyncFunction.Future.isFailed(futureHandle)
isFinished()
Short description

Can be used to poll if the async function execution is finished.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

isFinished

BOOL

True if the function execution is finished. False if not.

Sample
bIsFinished = Engine.AsyncFunction.Future.isFinished(handle)
wait()
Short description

Blocks and waits until the corresponding async function call finishes with optional timeout. Returns the result values of the function which was called asynchronously.

Parameters
Name Type Description

handle

HANDLE

The instance to use

timeoutMs

INT

The time in ms to wait for the function call to finish

Return values
Name Type Description

result1

AUTO

First result of the async function call (optional)

result2

AUTO

second result of the async function call (optional)

result3

AUTO

third result of the async function call (optional)

result4

AUTO

fourth result of the async function call (optional)

result5

AUTO

fifth result of the async function call (optional)

result6

AUTO

sixth result of the async function call (optional)

result7

AUTO

seventh result of the async function call (optional)

Sample
res1, res2, res3 = Engine.AsyncFunction.Future.wait(handle)

Engine.Event

Short description

This is a generic block to map to an flow input or output event. It can register to events so that it can be used as input block, or it can notify an event so that it can be used as output block. It supports level and dirac signals.

Functions

create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
handle = Engine.Event.create()
notify()
Short description

Notifies the specified event name. The event has to be added by the user to the manifest.

Parameters
Name Type Description

handle

HANDLE

signal

BOOL

The level/Dirac signal which triggers the event notify.

Sample
Engine.Event.notify(handle, signal)
setEventName()
Short description

Name of the event to which the block registers to (OnEvent-event) or which the block notifies (notify-function). The event has to exist in the manifest in both cases. If it is a level-based event, it must have one bool parameter declared in the manifest. If it is a dirac-based event, it must have no parameter declared in the manifest.

Parameters
Name Type Description

handle

HANDLE

eventName

STRING

Sample
Engine.Event.setEventName(handle, eventName)

Events

OnEvent
Short description

Register to the specified event name and provides its occurrences as signal. If the event has no bool parameter, it is a dirac event. if the event has a bool parameter, it is a level event.

Parameters
Name Type Description

handle

HANDLE

signal

BOOL

The level/Dirac signal which is triggered by every event occurrence. If registered event has a bool parameter, the value is provided as level.

Sample
Engine.Event.OnEvent(handle, signal)

Engine.EventBinding

Short description

Serves a new event and allows binding to an existing event including mapping the parameters to the new event notify. This is useful e.g. to bind handle based events to a static events and allow registration to them from a Flow block, but still configure it conveniently from a script.

Functions

bindParameters()
Short description

Adds parameter binding definitions. Could be called several times and adds them to the already bound ones. If not called at all, the parameters are directly mapped. The binding is specified from the registered event to the binding served event. A binding definition could be a position info or any other fix value. A position binding definition is done as string with a "$" as prefix like "$1". A position binding definition could be also the manifest parameter name of the served event. A fix value binding could be any CROWN type. If it should be a string starting with "$", then the first $ needs to be escaped to don’t be interpreted as position binding.

Parameters
Name Type Description

handle

HANDLE

The instance to use

binding1

AUTO

One binding definition

binding2

AUTO

second binding definition (optional)

binding3

AUTO

third binding definition (optional)

binding4

AUTO

fourth binding definition (optional)

binding5

AUTO

fifth binding definition (optional)

binding6

AUTO

sixth binding definition (optional)

binding7

AUTO

seventh binding definition (optional)

Return values
Name Type Description

success

BOOL

True if binding was correctly specified and is added

Sample
-- Maps to the target event:
-- second parameter of the event notify as first parameter
-- first parameter of the event notify as second parameter
-- integer value "1" as third parameter
-- content of lua variable "obj"
-- boolean value "true"
Engine.EventBinding.bindParameters(handle, "$2", "$1", 1, obj, true)
create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
-- Create a simple binding to a handle-based event binding:
handle = Engine.EventBinding.create()
handle:setEvent("Provider.OnSomeEvent", providerHandle) -- The providerHandle is the handle to the sample provider "Provider.OnSomeEvent"
-- Serve the new event. After that the event is directly active and will be thrown if the bound event is thrown:
handle:serve("MyCrown.OnMyEvent")
getNotifyFunction()
Short description

Returns the function name which is served and can be called to trigger manually a notify on the served event. This function name is also used internally to register at the bound event. Might be useful to trigger event notifies manually.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

servedFunction

STRING

The function name of the function to notify the event.

Sample
eventNotifyFuncName = Engine.EventBinding.getNotifyFunction(handle)
serve()
Short description

Serves a new event with the binding and returns true if successfully served. After this call the event can be registered by others and might get directly notified. If a event name is specified, the event must be available in the manifest. If no event name is specified, it generates an unique one and returns it. This is useful to directly bind a event notify without having it in the manifest.

Parameters
Name Type Description

handle

HANDLE

The instance to use

serveEventName

STRING

The event name including the crown name which should be served by this binding

Return values
Name Type Description

success

BOOL

Returns true if successfully served. False if already served by someone else

genServedEventName

STRING

If no event name was specified as parameter, a generated unique one is returned

Sample
Engine.EventBinding.serve(handle, "MyCrown.OnMyEvent")
setEvent()
Short description

Sets the bound event name to register to. If the event is handle based, the handle can be passed as second parameter to this function, so that the binding is done on the event on that handle. If a handle is set, the bindParameters function operates only on the event parameters after the handle. The handle is hold as long as the EventBinding exists.

Parameters
Name Type Description

handle

HANDLE

The instance to use

eventName

STRING

The event name which is used for registration

eventHandle

HANDLE

The optional handle on which the event should be registered. The handle is hold as long as the EventBinding exists.

Sample
-- Static event:
Engine.EventBinding.setEvent(handle, "Provider.OnEvent")
-- Handle based event:
Engine.EventBinding.setEvent(handle, "Provider.OnEvent", providerHandle)

Engine.FunctionBinding

Short description

Serves a new function and allows binding to an existing function including mapping the parameters and results to the target function call. This is useful e.g. to bind handle based function to a static function and allow calling them from a Flow block, but still configure it conveniently from a script.

Functions

bindParameters()
Short description

Adds parameter binding definitions. Could be called several times and adds them to the already bound ones. If not called at all, the parameters are directly mapped. The binding is specified from the binding served function to the target function. A binding definition could be a position info or any other fix value. A position binding definition is done as string with a "$" as prefix like "$1". A position binding definition could be also the manifest parameter name of the served function. A fix value binding could be any CROWN type. If it should be a string starting with "$", then the first $ needs to be escaped to don’t be interpreted as position binding.

Parameters
Name Type Description

handle

HANDLE

The instance to use

binding1

AUTO

One binding definition

binding2

AUTO

second binding definition (optional)

binding3

AUTO

third binding definition (optional)

binding4

AUTO

fourth binding definition (optional)

binding5

AUTO

fifth binding definition (optional)

binding6

AUTO

sixth binding definition (optional)

binding7

AUTO

seventh binding definition (optional)

Return values
Name Type Description

success

BOOL

True if binding was correctly specified and is added

Sample
-- Maps to the target function:
-- second parameter of the function call as first parameter
-- first parameter of the function call as second parameter
-- integer value "1" as third parameter
-- content of lua variable "obj"
-- boolean value "true"
Engine.FunctionBinding.bindParameters(handle, "$2", "$1", 1, obj, true)
bindResults()
Short description

Adds result binding definitions. Could be called several times and adds them to the already bound ones. If not called at all, the parameters are directly mapped. The binding is specified from the target function to the binding served function. A binding definition could be a position info or any other fix value. A position binding definition is done as string with a "$" as prefix like "$1". A position binding definition could be also the manifest result name of the target function. A fix value binding could be any CROWN type. If it should be a string starting with "$", then the first $ needs to be escaped to don’t be interpreted as position binding.

Parameters
Name Type Description

handle

HANDLE

The instance to use

binding1

AUTO

One binding definition

binding2

AUTO

second binding definition (optional)

binding3

AUTO

third binding definition (optional)

binding4

AUTO

fourth binding definition (optional)

binding5

AUTO

fifth binding definition (optional)

binding6

AUTO

sixth binding definition (optional)

binding7

AUTO

seventh binding definition (optional)

Return values
Name Type Description

success

BOOL

True if binding was correctly specified and is added

Sample
Engine.FunctionBinding.bindResults(handle, "$2", "$1", 1, obj, true)
create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
-- Create a simple binding to a handle-based function binding and register it at a provider:
handle = Engine.FunctionBinding.create()
handle:setFunction("Algo.process", algoHandle) -- The algoHandle is the handle to the sample function "Algo.process"
-- register the handle function at a provider:
SomeProvider.register(provHandle,  "OnSomeEvent", handle:serve() )
lock()
Short description

Locks all further function calls and makes them return instead of calling the target function. This is useful e.g. to reconfigure handle which is bound to the function call. Attention: Take care to keep the locking time as less as possible.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Sample
Engine.FunctionBinding.lock(handle)
serve()
Short description

Serves a new function with the binding and returns true if successfully served. After this call the function can be called by others. If a function name is specified, the function must be available in the manifest. If no function name is specified, it generates an unique one and returns it. This is useful to directly bind a function call without having it in the manifest.

Parameters
Name Type Description

handle

HANDLE

The instance to use

serveFuncName

STRING

The function name including the crown name which should be served by this binding

Return values
Name Type Description

success

BOOL

Returns true if successfully served. False if already served by someone else

genServedFuncName

STRING

If no function name was specified as parameter, a generated unique one is returned

Sample
Engine.FunctionBinding.serve(handle, "MyCrown.newFunction")
setFunction()
Short description

Sets the target function name to call. If the function is handle based, the handle can be passed as second parameter to this function, so that it is automatically set as first parameter for every function call. If a handle is set, the bindParameters function operates only on the function parameters after the handle, so the handle is implicitly added every time. The handle is hold as long as the FunctionBinding exists.

Parameters
Name Type Description

handle

HANDLE

The instance to use

functionName

STRING

The function name which is called by this binding

functionHandle

HANDLE

The optional handle which is automatically set as first parameter to every function call. The handle is hold as long as the FunctionBinding exists.

Sample
-- Static function:
Engine.FunctionBinding.setFunction(handle, "Algo.function")
-- Handle based function:
Engine.FunctionBinding.setFunction(handle, "Algo.function", algoHandle)
unlock()
Short description

Sets the target function to call.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Sample
Engine.FunctionBinding.unlock(handle)

Engine.SyncEvent

Short description

Registers for the specified event and queues up all event occurrences. The user can synchronously wait for the event occurrence and their event parameters. There is an internal queue used which queues all events up. This is useful if the user needs to get the status of an event at a specified position during processing.

Functions

clear()
Short description

Clears all currently queued events. Pay attention that directly during returning from this function there might be events already added again.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Sample
Engine.SyncEvent.clear(handle)
close()
Short description

Closes the internal queue and removes the registrations on the event. All currently queued events are discarded.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Sample
Engine.SyncEvent.close(handle)
create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
-- Create a simple sync event and
handle = Engine.SyncEvent.create()
handle:setEvent("Provider.OnEvent", provHandle)
handle:open()
r1, r2, r3 = handle:wait()
getSize()
Short description

Returns the current number of queued calls. Pay attention that directly during returning from this function there might be events already added again.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

queueSize

INT

The current number of queues which are queued in the internal queue

Sample
local queueSize = Engine.SyncEvent.getSize(handle)
open()
Short description

Opens the internal queue by registering for the event which was set before. After this call the events are received and queue internally up. Returns true if the it was successfully registered and opened. Additionally it returns the internal served function name which also can be used manually by the user to enqueue the event.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

success

BOOL

True if successfully registered and opened. False if e.g. the event handle was not valid and registering was not possible or the event name was not valid

enqueueFunctionName

STRING

If successfully opened, the function name is returned here to manually enqueue to the event queue or register at further events

Sample
bSuccess, enqueueFunc = Engine.SyncEvent.open(handle)
poll()
Short description

Polls and returns the event parameters if there is already an event queued. Returns nothing if there was no event queued.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

result1

AUTO

First result of the async function call (optional)

result2

AUTO

second result of the async function call (optional)

result3

AUTO

third result of the async function call (optional)

result4

AUTO

fourth result of the async function call (optional)

result5

AUTO

fifth result of the async function call (optional)

result6

AUTO

sixth result of the async function call (optional)

result7

AUTO

seventh result of the async function call (optional)

setDiscardIfFull()
Short description

Sets the behaviour for adding events to the queue if the queue is full. Per default the oldest element is discarded. To discard the newest to be added element, call this function with parameter true.

Parameters
Name Type Description

handle

HANDLE

The instance to use

bDiscardIfFull

BOOL

Set to true to discard the newest item which is currently added instead of discarding the oldest element

Sample
Engine.SyncEvent.setDiscardIfFull(handle, true)
setEvent()
Short description

Sets the event name to register to. If the event is handle based, the handle can be passed as second parameter to this function, so that the event is registered at the handle. The handle is hold as long as the SyncEvent exists. This function is also optional. If not called, the user can directly use the open function and use the returned function name to manually enqueue to the queue or register manually at events.

Parameters
Name Type Description

handle

HANDLE

The instance to use

eventName

STRING

The event name which is used for registration

eventHandle

HANDLE

The optional handle on which the event should be registered. The handle is hold as long as the SyncEvent exists.

Sample
-- Static event:
Engine.SyncEvent.setEvent(handle, "Provider.OnEvent")
-- Handle based event:
Engine.SyncEvent.setEvent(handle, "Provider.OnEvent", providerHandle)
setMaxQueueSize()
Short description

Sets the maximum queue size of the internal event queue. Per default the queue is set to infinite size (=0). If the max queue size is reached, the oldest element is discarded per default. To change that behaviour use the setDiscardIfFull-Function.

Parameters
Name Type Description

handle

HANDLE

The instance to use

maxQueueSize

INT

The max number of events to queue. Per default 0 (=infinite)

Sample
Engine.SyncEvent.setMaxQueueSize(handle, 10)
wait()
Short description

Blocks and waits until there is an event in the queue with optional timeout. Returns the parameter values of the event which was called received. If there is already an event queued, this function directly returns.

Parameters
Name Type Description

handle

HANDLE

The instance to use

timeoutMs

INT

The time in ms to wait for the function call to finish

Return values
Name Type Description

result1

AUTO

First result of the async function call (optional)

result2

AUTO

second result of the async function call (optional)

result3

AUTO

third result of the async function call (optional)

result4

AUTO

fourth result of the async function call (optional)

result5

AUTO

fifth result of the async function call (optional)

result6

AUTO

sixth result of the async function call (optional)

result7

AUTO

seventh result of the async function call (optional)

Engine.WebServer

Short description

Provides functions for managing the engine’s embedded webserver.

Functions

setCrownEndpointEnabled()
Short description

Enable or disable the CROWN endpoint of the engine’s embedded webserver. If the endpoint is disabled REST and websocket communication on the URL 'api/crown' is no longer possible. Accessibility of the device page and communication via the 'api' URL is not affected, however.

Parameters
Name Type Description

enabled

BOOL

True to enable, false to disable.

Sample
Engine.WebServer.setCrownEndpointEnabled(false)
setEnabled()
Short description

Enable or disable the engine’s embedded webserver. If disabled the device page will not be accessible any more. REST and websocket communication is no longer possible.

Parameters
Name Type Description

enabled

BOOL

True to enable, false to disable.

Sample
Engine.WebServer.setEnabled(false)

FTPClient

Short description

Provides FTP/FTPS client functionality. Supports plain FTP and FTPS (FTP over SSL). FTPS can be configured to be used in explicit or implicit mode. SFTP (SSH File Transfer Protocol) is not supported. Important note: If your application design requires FTP connections to be kept open in idle mode you must use the setKeepAliveInterval() function to enable keep-alive. Otherwise the internal connection is closed, resulting in an unnecessary reconnect when performing the next active operation.

Keywords

Ethernet

See also

Functions

cd()
Short description

Change the current directory on the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

directory

STRING

Directory to change to. Can be a relative or absolute path in FTP path notation.

Return values
Name Type Description

success

BOOL

Is true if directory has been changed successfully, false if an error occurred

Sample
success = FTPClient.cd(handle, "/absolute/path")
connect()
Short description

Connect to a FTP server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

login

STRING

User name for login.

password

STRING

Login password.

Return values
Name Type Description

success

BOOL

Is true if connection is established, false if an error occurred

Sample
success = FTPClient.connect(handle, "user", "password")
create()
Short description

Creates a new FTP client instance.

Return values
Name Type Description

handle

HANDLE

The instance handle of the FTP client

Sample
handle = FTPClient.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

disconnect()
Short description

Disconnect an open connection to a FTP server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

Return values
Name Type Description

success

BOOL

Is true if connection is closed, false if an error occurred

Sample
success = FTPClient.disconnect(handle)
get()
Short description

Download a file from the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

filename

STRING

Target name of the file to download. Can be a relative or absolute path in FTP path notation.

Return values
Name Type Description

success

BOOL

Is true if the file has been downloaded successfully, false if an error occurred.

data

BINARY

Content of the file.

Sample
success, data = FTPClient.get(handle, "/path/to/file")
getFile()
Short description

Download a file from the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

remoteSource

STRING

Target name of the file to download. Can be a relative or absolute path in FTP path notation.

localDestination

STRING

Destination path of the file to download.

Return values
Name Type Description

success

BOOL

Is true if the file has been downloaded successfully, false if an error occurred.

Sample
success = FTPClient.getFile(handle, "/path/to/file", "private/file")
getLastError()
Short description

Get information about the last FTPClient method invocation. Returns error code and error text. In case communication with the FTP server has taken place the FTP server code is delivered as code. This might be a error code or a success code.See https://en.wikipedia.org/wiki/List_of_FTP_server_return_codes . In case a libcurl error occurs it is returned as negative value. See https://curl.haxx.se/libcurl/c/libcurl-errors.html

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

Return values
Name Type Description

errorCode

INT

Error code of the FTP server

errorText

STRING

Additional information on the error

Sample
errorCode, errorText = FTPClient.getLastError(handle)
isConnected()
Short description

Returns whether the FTP client is connected to a server

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

Return values
Name Type Description

connectStatus

BOOL

Is true if the connection exists

Sample
connectStatus = FTPClient.isConnected(handle)
list()
Short description

List the content of a directory on the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

directory

STRING

Directory to list. Can be a relative or absolute path in FTP path notation.

onlyNames

BOOL

If true (default), the FTP command NLST is used and only the names of the directory entries are returned. If false, the FTP command LIST is used instead. LIST returns additional information about each file, but the format is server-specific.

Return values
Name Type Description

success

BOOL

Is true if directory has been listed successfully, false if an error occurred

directoryEntries

STRING

List of directory entries.

Sample
success, directoryEntries = FTPClient.list(handle, "/absolute/path")
mkdir()
Short description

Create a directory on the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

directory

STRING

Directory to create. Can be a relative or absolute path in FTP path notation.

Return values
Name Type Description

success

BOOL

Is true if directory has been created successfully, false if an error occurred

Sample
success = FTPClient.mkdir(handle, "/absolute/path")
put()
Short description

Upload a file to the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

filename

STRING

Target name of the file to upload. Can be a relative or absolute path in FTP path notation.

data

BINARY

Content of the file to upload.

appendMode

BOOL

Append mode. If true, the data is appended to the file if it already exists, otherwise the file is created. Default is false.

Return values
Name Type Description

success

BOOL

Is true if the file has been uploaded successfully, false if an error occurred.

Sample
success = FTPClient.put(handle, "/path/to/file", data)
putFile()
Short description

Upload a file to the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

remoteDestination

STRING

Target name of the file to upload. Can be a relative or absolute path in FTP path notation.

localSource

STRING

Source path of the file to upload.

appendMode

BOOL

Append mode. If true, the data is appended to the file if it already exists, otherwise the file is created. Default is false.

Return values
Name Type Description

success

BOOL

Is true if the file has been uploaded successfully, false if an error occurred.

Sample
success = FTPClient.putFile(handle, "/path/to/file", "resources/file")
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

rename()
Short description

Rename a file on the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

filenameFrom

STRING

File to rename. Can be a relative or absolute path in FTP path notation.

filenameTo

STRING

New filename.

Return values
Name Type Description

success

BOOL

Is true if the file has been renamed successfully, false if an error occurred.

Sample
success = FTPClient.rename(handle, "fileOld.txt", "fileNew.txt")
rm()
Short description

Remove a file on the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

filename

STRING

File to remove. Can be a relative or absolute path in FTP path notation.

Return values
Name Type Description

success

BOOL

Is true if the file has been removed successfully, false if an error occurred.

Sample
success = FTPClient.rm(handle, "file.txt")
rmdir()
Short description

Remove a directory on the server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

directory

STRING

Directory to remove. Can be a relative or absolute path in FTP path notation.

Return values
Name Type Description

success

BOOL

Is true if directory has been removed successfully, false if an error occurred

Sample
success = FTPClient.rmdir(handle, "/absolute/path")
setCABundle()
Short description

Configures the certificate authority bundle to be used for verifying server certificates.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTPClient.

bundleFile

STRING

Path to a certificate bundle in PEM format.

Sample
FTPClient.setCABundle(handle, "private/CA.pem")
setClientCertificate()
Short description

Enables client authentication. A client certificate and a private key must be provided. The passphrase for the private key is optional. Supported file formats are PEM, DER and PKCS#12 (depending on SSL engine) for the client certificate and PEM and DER for the private key. The format is selected by inspecting the extension of the provided file. If no valid extension is specified the engine defaults to PEM format.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTPClient.

certificateFile

STRING

Path to a certificate file in PEM/DER/PKCS#12 format.

keyFile

STRING

Path to file containing the client’s private key in PEM/DER format.

passphrase

STRING

Optional passphrase for the private key.

Sample
FTPClient.setClientCertificate(handle, "private/cert.pem", "private/privateKey.pem", "mypassphrase")
setConnectTimeout()
Short description

Configures the connect/accept timeout.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

timeoutMs

INT

Timeout for connect/accept in milliseconds. Default is 5000ms.

Sample
FTPClient.setConnectTimeout(handle, 1000)
setHostnameVerification()
Short description

Enables/disables hostname verification. This can be useful if the site to connect to uses a different host name than what is mentioned in the server certificate commonName (or subjectAltName) fields. Disabling this verification makes the connection less secure.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTPClient.

enabled

BOOL

True to enable hostname verification, false to disable. Default is enabled.

Sample
FTPClient.setHostnameVerification(handle, false)
setInterface()
Short description

Sets the interface to use for connecting. Before setting the first interface is used.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

ifName

ENUM EthernetInterfaces

One of the available interfaces

Sample
FTPClient.setInterface(handle, "ETH1")
setIpAddress()
Short description

Configures the ip address to connect to.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

ipAddress

STRING

IP address of the server.

Sample
FTPClient.setIpAddress(handle, "192.168.0.20")
setKeepAliveInterval()
Short description

Activates sending of keep-alive commands with a given time periode. A time periode of 0 disables sending of keep-alive commands. Can be executed before or during a FTP connection.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

sec

INT

Time periode in seconds.

Sample
FTPClient.setKeepAliveInterval(handle, 30)
setMode()
Short description

Sets the mode for following file transfers.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

mode

ENUM TransferMode

Transfer mode that is to be set.

Return values
Name Type Description

success

BOOL

Is true if mode has been set successfully, false if an error occurred

Sample
success = FTPClient.setMode(handle, "binary")
setPassiveMode()
Short description

Enable or disable the FTP passive mode. This can be done before connecting to a FTP server. Disabled passive mode is the default setting of the FTPClient

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

state

BOOL

True set passive mode. False set active mode

Return values
Name Type Description

success

BOOL

Is true if the operation was successful. If false, use getLastError for more details on the error

Sample
success = FTPClient.setPassiveMode(handle, true)
setPeerVerification()
Short description

Enables/disables peer verification. This can be useful when connecting to a site that is not using a certificate signed by one of the certs in the CA bundle. Disabling this verification makes the connection A LOT LESS SECURE.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTPClient.

enabled

BOOL

True to enable peer verification, false to disable. Default is enabled.

Sample
FTPClient.setPeerVerification(handle, false)
setPort()
Short description

Configures the port for the control connection.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

port

INT

Port for control connection. Default is 21.

Sample
FTPClient.setPort(handle, 1234)
setSecurityProtocol()
Short description

Sets the security protocol to use.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTPClient.

protocol

ENUM SecurityProtocol

Security protocol and mode to use. Default is none (plain FTP without TLS). To use FTPS, a certificate authority bundle needs to be configured. See function setCABundle.

Sample
FTPClient.setSecurityProtocol(handle, "FTPS_EXPLICIT")
setTransmitTimeout()
Short description

Configures the transmit timeout.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

timeoutMs

INT

Timeout for transmits in milliseconds. If not set the value of the connect timeout is used.

Sample
FTPClient.setTransmitTimeout(handle, 5000)
setVerbose()
Short description

Tell the FTPClient to print log messages during the transfer. This includes the debug output of the curl library This method must be called before connecting to the FTP server.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

state

BOOL

True set the FTPClient in verbose state

Sample
FTPClient.setVerbose(handle, true)

Events

OnDisconnected
Short description

Event that is thrown when the FTPServer disconnects the connection

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP client

FTPServer

Short description

Provides FTP server functionality. Create a new FTP server instance by calling the create function first. You may set the server port and the maximum number of connections via the setServerPort and setMaxConnections functions. Default is 21 for the server port and 10000 connections. Users may be added or removed using the addUser and removeUser functions. Login names must be unique per FTP server instance. Please note that you must add at least one user, even if you want anonymous login. Leave the password empty in that case. The data port range for PASV mode may be set with the setDataPortRange function. Several other parameters can be changed using the associated set functions, but meaningful default values have been selected already. Start the server using the start function and stop it (if needed) by calling stop.

Keywords

Ethernet

See also

Functions

addUser()
Short description

Add a user account

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

login

STRING

Login name for the user account

password

STRING

Password for the user account. Leave empty to not check the password.

startDirectory

STRING

Root directory for the user account. Only paths relative to the app home directory are allowed.

Return values
Name Type Description

success

BOOL

Is true if user was added, false if an error occurred

Sample
success = FTPServer.addUser(handle, "anonymous", "", "public")
create()
Short description

Creates a new FTP server instance.

Return values
Name Type Description

handle

HANDLE

The instance handle of the FTP server

Sample
handle = FTPServer.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

removeUser()
Short description

Remove a user account

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

login

STRING

Login name of the user account which is to be removed

Return values
Name Type Description

success

BOOL

Is true if user was removed, false if an error occurred

Sample
success = FTPServer.removeUser(handle, "anonymous")
setCheckPassDelay()
Short description

Configure the forced delay between subsequent login attempts in milliseconds

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

delay

INT

Delay between subsequent login attempts in milliseconds. Default is 500.

Sample
FTPServer.setCheckPassDelay(handle, 5000)
setDataPortRange()
Short description

Set the range of data ports available for PASV mode port selection

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

rangeBegin

INT

First port of range (inclusive).

rangeEnd

INT

Last port of range (inclusive).

Sample
FTPServer.setDataPortRange(handle, 5000, 6000)
setInterface()
Short description

Sets the interface to use for connecting.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

ifName

ENUM EthernetInterfaces

One of the available interfaces

Return values
Name Type Description

success

BOOL

Is true if interface was set successfully, false if an error occurred

Sample
FTPServer.setInterface(handle, "ETH1")
setMaxConnections()
Short description

Configures the maximum number of connections allowed on the control port.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

connections

INT

Maximum number of connections that is allowed. Default is 10000.

Return values
Name Type Description

success

BOOL

Is true if max connections were set successfully, false if an error occurred

Sample
success = FTPServer.setMaxConnections(handle, 100)
setServerPort()
Short description

Configure the port number for the FTP server’s control connection.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

port

INT

Number of the port to listen on. Default is 21.

Return values
Name Type Description

success

BOOL

Is true if server port was set successfully, false if an error occurred

Sample
success = FTPServer.setServerPort(handle, 33)
setTransferBufferSize()
Short description

Sets the size of the transfer buffer used for data connections

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

bufferSize

INT

Buffer size for data connection transfers. Default is 32768.

Sample
FTPServer.setTransferBufferSize(handle, 10000)
start()
Short description

Start the FTP server

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

Return values
Name Type Description

success

BOOL

Is true when the FTP server is running, false if an error occurred.

Sample
success = FTPServer.start(handle)
stop()
Short description

Stop the FTP server

Parameters
Name Type Description

handle

HANDLE

The instance handle of the FTP server

Return values
Name Type Description

success

BOOL

Is true when the FTP server has been stopped successfully, false if an error occurred.

Sample
FTPServer.stop(handle)

Events

OnStore
Short description

The event which is triggered after a file has been uploaded.

Parameters
Name Type Description

handle

HANDLE

This is a handle event and must be registered on the handle

fileName

STRING

The name of the file that has been uploaded.

filePath

STRING

The path where the file has been put.

FieldBus

Short description

Provides field bus access. This API is intended for field bus slave devices and allows them exchange data with a PLC. It works for all field bus protocols like PROFINET, EtherNet/IP and EtherCAT. Which field bus protocols are actually available depends on the device. How to enable the field bus functionality or select a specific protocol is also device specific. Some devices offer these settings via the SOPAS Engineering Tool. There is no possibility to select the protocol via this API. To integrate the device into PLC projects you need an appropriate device description file. These are available via the SICK support portal. - PROFINET: GSDML file - EtherNet/IP: EDS file - EtherCat: ESI file Devices which implement this API offer two independent ways to communicate process data with a PLC: - For each direction (output from PLC to device and input from device to PLC), there is a field "ControlBits" with a length of 16 bits. These fields can be used freely by your application, there is no predefined meaning for the individual bits. - The rest of the cyclic process data can be used in two different modes: - In Confirmed Messaging mode, it is used as a transfer channel for the SICK Confirmed Messaging protocol. This protocol allows to send arbitrary strings in both directions. The protocol can also handle strings that are longer than the size of the cyclic process data. This works by splitting them up in several fragments which are transferred and acknowledged sequentially. To use this channel from the PLC side, SICK offers ready-to-use function blocks for Confirmed Messaging for various PLCs. - In Raw mode, the user receives and sets the process data directly without any protocol.

Functions

close()
Short description

Stops communication to the field bus

Parameters
Name Type Description

handle

HANDLE

The FieldBus handle

Sample
FieldBus.close(busHandle)
create()
Short description

Creates a new instance. This can fail if field bus functionality is disabled in the device. Some devices offer a switch to enable and select the type of field bus via the SOPAS Engineering Tool.

Parameters
Name Type Description

mode

ENUM CreateMode

Optional create mode. Default is 'AUTOMATIC_OPEN'.

Return values
Name Type Description

handle

HANDLE

The new FieldBus. nil if FieldBus is disabled.

Sample
busHandle = FieldBus.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

open()
Short description

Starts the communication to the field bus. This function only has to be called when the handle was created with CreateMode "EXPLICIT_OPEN". Otherwise, open is done automatically on handle create.

Parameters
Name Type Description

handle

HANDLE

The FieldBus handle

Sample
FieldBus.open(busHandle)
readControlBitsIn()
Short description

Gets the current value of the control bits transmitted to the PLC

Parameters
Name Type Description

handle

HANDLE

The FieldBus handle

Return values
Name Type Description

controlBitsIn

INT

the control bits

Sample
local controlBitsIn = FieldBus.readControlBitsIn(busHandle)
readControlBitsOut()
Short description

Gets the current value of the control bits received from the PLC

Parameters
Name Type Description

handle

HANDLE

The FieldBus handle

Return values
Name Type Description

controlBitsOut

INT

the control bits

Sample
local controlBitsOut = FieldBus.readControlBitsOut(busHandle)
register()
Short description

This function is used to register for events from the FieldBus

Parameters
Name Type Description

handle

HANDLE

eventname

STRING

The event to register to

callback

STRING

Function name to call when an event occurs

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

Sample
Fieldbus.register(handle, 'OnNewData', callback)
setMode()
Short description

Sets the transmission mode. Default is "CONFIRMED_MESSAGING".

Parameters
Name Type Description

handle

HANDLE

The FieldBus handle

mode

ENUM TransmissionMode

Transmission mode

Sample
FieldBus.setMode(busHandle, "RAW")
transmit()
Short description

Transmits data through the field bus to the PLC. This function does not affect the control bits, only the rest of the cyclic process data. Behavior depends on transmission mode (see function setMode): In mode RAW: Directly set the parameter data as cyclic process data. If data is too long to be transmitted according to the current PLC connection settings, the data is trunacated. This function returns the actual number of bytes that were transmitted. In mode CONFIRMED_MESSAGING: - If there is no connection to a PLC, the function fails and returns immediately with return value 0. - If there is a connection to a PLC, the function returns after transmission of the data starts. The function might block for up to 10 seconds if it is not possible to start sending immediately. This is the case if other data from previous calls to transmit is still being transmitted or if the PLC did not confirm a previous transmit yet. If it is not possible to start sending in 10 seconds, the function fails with return value 0. - The function does not wait till the transmission of the data is complete. - The function does not wait for the confirmation from the PLC.

Parameters
Name Type Description

handle

HANDLE

The FieldBus handle

data

BINARY

The data which is to be transmitted. Up to 4094 bytes can be transmitted with a single call. If the size is larger, only the first 4094 bytes will be transmitted.

Return values
Name Type Description

numberOfBytesTransmitted

INT

Number of bytes transmitted; 0 if transmit failed.

Sample
bytesTransmitted = FieldBus.transmit(busHandle, "Hello PLC")
writeControlBitsIn()
Short description

Sets and transmits the value of the control bits to the PLC

Parameters
Name Type Description

handle

HANDLE

The FieldBus handle

controlBits

INT

The control bits to write

bitMask

INT

The bitmask to use

Sample
FieldBus.writeControlBitsIn(busHandle, controlBits, bitMask)

Events

OnControlBitsOutChanged
Short description

This event is thrown when the control bits set by the PLC have changed.

Parameters
Name Type Description

handle

HANDLE

The FieldBus handle

ctrlBits

INT

ctrl bits out

OnNewData
Short description

This event is thrown when new data has been received from the PLC through the field bus.

Parameters
Name Type Description

handle

HANDLE

The FieldBus handle

data

BINARY

File

Short description

Provides file operation functions. The application has access to different folders on the filesystem of the device. There are the following app related paths: - The "resources" folder is read-only and can be used to read app resources like parameter files, images etc. - The "private" directory can be used to store persistent app data privately. This data is backup-ed with together with the app. - The "public" directory can be used for shared access with other applications. All applications have access to this folder. The "private" and "public" folders should only be used as persistent storage and NOT to continuously process data. ATTENTION: The underlying hardware could get broken if overused! Consider to use API functions which don’t use files or use the ram filesystem mounted drive of the device. Additionally it is possible to access the mounted drives of a device. Which mounted drives are available is defined by the device in a CROWN enum named "MountedDrives". E.g. there could be a path "/usb/0" for the first USB drive, or "/sdcard/0" for the first SD Card drive.

Functions

close()
Short description

Closes a file identified by a handle. If not explicitly called, the file is automatically closed on destruction of the handle.

Parameters
Name Type Description

handle

HANDLE

The filehandle of an opened file.

Sample
File.close(handle)
copy()
Short description

Copies the specified file or full path to another file or path. If the target file exists it is overwritten. If the target path exists it is integrated in the target structure.

Parameters
Name Type Description

fileSourcePath

STRING

The path to copy from

fileTargetPath

STRING

The path to copy to

Return values
Name Type Description

success

BOOL

True if successful, false if source path does not exist or cannot overwrite new files.

Sample
local success = File.copy("/private/sourcefile.txt", "/private/targetfile.txt")
del()
Short description

Deletes a file or folder specified by a path. The path must start with "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). Deleting the "public", "private" or mounted drive itself is not allowed and returns false. Their contents can be deleted by iterating on their elements.

Parameters
Name Type Description

fileName

STRING

The path to the file/folder that is to be deleted

Return values
Name Type Description

success

BOOL

true if success

Sample
local success = File.del("/private/myfile.txt")
exists()
Short description

Checks if the given path or file exists. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).

Parameters
Name Type Description

fileName

STRING

The path to the file/folder that is to be checked

Return values
Name Type Description

result

BOOL

true if success

Sample
local bExists = File.exists("/private/myfile.txt")
extractPathElements()
Short description

Splits the specified path string into its elements path, file basename and file extension.

Parameters
Name Type Description

filePath

STRING

The path string to extract from

Return values
Name Type Description

path

STRING

The path of the file

basename

STRING

The base name of the file

extension

STRING

The file extension of the file

Sample
local path, basename, extension = File.extractPathElements("/private/thefile.txt")
getDiskFree()
Short description

Returns the remaining space of a specific path.

Parameters
Name Type Description

path

STRING

The name of the path to get the free space from.

Return values
Name Type Description

freeBytes

INT

The available bytes in the path.

Sample
local free = File.getDiskFree("/public")
getDiskUsage()
Short description

Returns the usage of a specific path.

Parameters
Name Type Description

path

STRING

The path to get the usage from.

Return values
Name Type Description

usedBytes

INT

The bytes used in the path.

Sample
local usage = File.getDiskUsage("/public")
getPath()
Short description

Returns the path of the file handle with which it was opened.

Parameters
Name Type Description

handle

HANDLE

The filehandle of an opened file.

Return values
Name Type Description

filePath

STRING

The path to the file that was opened. Nil if file handle is not open.

Sample
local path = File.getPath(handle)
isdir()
Short description

Checks if the given path is a folder. The path must start with "resources", "public", "private"or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).

Parameters
Name Type Description

fileName

STRING

The path to the file/folder that is to be deleted

Return values
Name Type Description

result

BOOL

true if success

Sample
local isDir = File.isdir("/private/myfile.txt")
list()
Short description

Lists all files and subdirectories in the specified directory non-recursively. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). Returns a list of file and directory names in the specified path.

Parameters
Name Type Description

filePath

STRING

The path to the folder to list

filter

STRING

A string to filter the results of the listing. Wildcards can be used.

Return values
Name Type Description

list

STRING

The list of file and directory names. Nil if specified filePath does not exist or is not a directory.

Sample
local fileList = File.list("/private/", "*.png")
listRecursive()
Short description

Lists all files and subdirectories in the specified directory recursively (without empty folders). The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). Returns a list of file and directory names in the specified path.

Parameters
Name Type Description

filePath

STRING

The path to the folder to list

Return values
Name Type Description

list

STRING

The list of file and directory names including the relative path to the specified directory. Nil if specified filePath does not exist or is not a directory.

Sample
local fileList = File.listRecursive("/private/")
mkdir()
Short description

Creates a new folder specified by a path. The path must start with "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).

Parameters
Name Type Description

fileName

STRING

The path to the folder that is to be created

Return values
Name Type Description

success

BOOL

true if success or already exists. false if not possible or is already a file.

Sample
local success = File.mkdir("/private/myfolder")
move()
Short description

Moves the specified file or full path to another file or path. If the target file exists it is overwritten. If the target path exists it is integrated in the target structure. If moving fails, parts of the source path may still exist, and the target path may be inconsistent or incomplete.

Parameters
Name Type Description

fileSourcePath

STRING

The path to move from

fileTargetPath

STRING

The path to move to

Return values
Name Type Description

success

BOOL

true if success. false if source path does not exist or cannot overwrite new files.

Sample
local success = File.move("/private/sourcefile.txt", "/private/targetfile.txt")
open()
Short description

Opens a file specified by a path and mode. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). The mode specifies if it is for reading or writing and if it is in ASCII or binary mode (standard POSIX modes). The file is created if it does not exist and is opened for writing. Returns a handle if successful, which needs to be used for further file functions. Open for reading might fail if the file does not exist or is already opened for writing. Open for writing might fail if the file is already opened for reading or writing, or if the "resources" folder is opened for writing (which is read-only).

Parameters
Name Type Description

filePath

STRING

The path to the file that is to be opened

mode

STRING

Use "r" or "rb" for reading, "w" or "wb" for writing, "a" or "ab" for append; "b" means binary, without "b" the OS could change control characters like CR or LF. Same syntax like in C fopen()

Return values
Name Type Description

handle

HANDLE

An indicator for accessing the file. Is nil if failed. See File CROWN description for error info.

Sample
local handle = File.open("/private/myfile.txt", "wb")
position()
Short description

Returns the current position of the file pointer.

Parameters
Name Type Description

handle

HANDLE

The filehandle of an opened file.

Return values
Name Type Description

position

INT

The current position of the file pointer.

Sample
local position = File.position(handle)
read()
Short description

Reads data from a file identified by a handle. The number of bytes to read can be specified. Continuous calls to read continue to read at the current position. If a read returns a binary of size 0, then there is no more data to read.

Parameters
Name Type Description

handle

HANDLE

The filehandle of an opened file.

length

INT

The number of bytes to read. Read the whole file if not specified or zero.

Return values
Name Type Description

data

BINARY

The data which was read from the file. Is nil if the file isn’t opened. Binary size is 0 if there is nothing more to read.

Sample
local data = File.read(handle, length)
seek()
Short description

Places the file pointer at the specified position. The next read will start at this position.

Parameters
Name Type Description

handle

HANDLE

The filehandle of an opened file.

position

INT

The position to jump to in the file.

Return values
Name Type Description

success

BOOL

True if seeking in the file was successful.

Sample
local success = File.seek(handle, 15)
size()
Short description

Returns the size of a file. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).

Parameters
Name Type Description

fileName

STRING

The path to the file

Return values
Name Type Description

fileSize

INT

size of file

Sample
local fileSize = File.size("/private/myfile.txt")
write()
Short description

Writes to a file identified by a handle.

Parameters
Name Type Description

handle

HANDLE

The filehandle of an opened file.

data

BINARY

The data to write into the file

Return values
Name Type Description

success

BOOL

True if the data was successfully written to the file.

Sample
local success = File.write(handle, "Hello")

File.Archive

Short description

Contains functionality to pack/unpack files as an archive.

File.Archive.ZIP

Short description

File Archive functionality to work with ZIP files. An archiver instance works with one ZIP archive at a time. To handle multiple ZIPs at a time, create multiple instances of the archiver. Loaded or added files must exist and are kept locked by this API until the handle is destroyed or close function is called. Both inflated and deflated ZIP archives can be read. ZIP file writing supports only inflated archives.

Functions

add()
Short description

Adds a file or whole directory from the filesystem to the archive. The specified file needs to exist and is locked until this class loads another zip file or close function is called. If there is already a file or folder with that archive path, it is overwritten.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

sourceFilePath

STRING

The path to the file or directory which should be added. E.g. '/private/sourceFile.txt'

archiveFilePath

STRING

The path in the archive to which the file or directory should be added. Must be a full file path including file name. Sub-directories are created automatically. Existing file is overwritten. Leave empty to add to root directory of the archive. E.g. 'archiveFolder/archiveFile.txt'

Return values
Name Type Description

success

BOOL

True if successfully added the file. False if the file does not exist.

Sample
local success = File.Archive.ZIP.add(handle, "/private/sourceFile.txt", "archiveFolder/archiveFile.txt")
create()
Short description

Creates a new ZIP archive instance to work on archives.

Return values
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

Sample
local handle = File.Archive.ZIP.create()
del()
Short description

Deletes a file or whole directory (including added files all sub-directories) from the archive. If the archive is afterwards saved or serialized, the specified archive path will not be part of it.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

archiveFilePath

STRING

The path in the archive which should be deleted. E.g. 'archiveFolder/archiveFile.txt'

Return values
Name Type Description

success

BOOL

True if successfully deleted the file or folder. False if there was nothing found in the archive path to delete.

Sample
local success = File.Archive.ZIP.del(handle, "archiveFolder/archiveFile.txt")
deserialize()
Short description

Loads a zip archive from the specified binary buffer. This is useful if zip file is already present in memory so that it does not need to be stored to file to load it. E.g. if the zip file content is directly received from a TCPIP client or similar.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

archiveBuffer

BINARY

The binary buffer containing the whole archive.

Return values
Name Type Description

success

BOOL

True if successfully loaded the zip. False if the buffer content is not valid or no zip file.

Sample
local success = File.Archive.ZIP.deserialize(handle, buffer)
extract()
Short description

Extracts a file from the archive to the filesystem.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

archiveFilePath

STRING

The path in the archive from which the file or directory should be extracted. E.g. 'archiveFolder/archiveFile.txt'. Leave empty to extract whole archive.

targetFilePath

STRING

The path to the file or directory which should be extracted to. Sub-directories are created automatically. E.g. '/private/targetFile.txt'

Return values
Name Type Description

success

BOOL

True if successfully extracted the file. False if the file does not exist or could not extracted to the target path or password does not work on the file.

Sample
local success = File.Archive.ZIP.extract(handle, "archiveFolder/archiveFile.txt", "/private/targetFile.txt")
getComment()
Short description

If an archive is loaded, return the current comment set on the loaded archive. If the setComment function was used, it still returns the comment of the loaded archive and not the one which is newly set.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

Return values
Name Type Description

comment

STRING

The comment text is set on the loaded archive. Nil if there is no loaded archive.

list()
Short description

Lists the content from the current loaded archive. The paths are relative and therefore don’t start with a leading "/".

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

Return values
Name Type Description

content

STRING

List of file paths in the current loaded archive

Sample
local fileList = File.Archive.ZIP.list(handle)
load()
Short description

Loads a zip archive from the specified file. The loaded file keeps locked until this class loads another zip file or close function is called. If loading fails a previously loaded zip file state is cleared.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

sourceFilePath

STRING

The path to the zip file that is to be loaded. E.g. '/private/load.zip'

Return values
Name Type Description

success

BOOL

True if successfully loaded the zip. False if file does not exist or is no zip file

Sample
local success = File.Archive.ZIP.load(handle, "/private/load.zip")
mkdir()
Short description

Creates an empty folder. If there is already a file or folder with that archive path, it is overwritten. Remember that files to be added don’t need a folder to be created first, so this function is only if there should be an empty folder in the archive. If it is a sub path, it creates the whole folder.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

archiveFilePath

STRING

The path in the archive which should be created as folder. E.g. 'archiveFolder/newFolder'

Return values
Name Type Description

success

BOOL

True if successfully created the new folder.

Sample
local success = File.Archive.ZIP.mkdir(handle, "archiveFolder/newFolder")
read()
Short description

Extracts a single file from the archive and returns it as binary buffer. This is useful if the file needs to be in memory so that it could be directly used for further processing. E.g. if the zip file is directly sent to TCPIP client or similar.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

archiveFilePath

STRING

The path in the archive from which the file or directory should be extracted. E.g. 'archiveFolder/archiveFile.txt'

Return values
Name Type Description

fileBuffer

BINARY

The binary buffer containing the zip file. Nil on error if file does not exist or password does not work on the file.

Sample
local buffer = File.Archive.ZIP.read(handle, "archiveFolder/archiveFile.txt")
save()
Short description

Saves the current zip file state to the specified file path. Any existing file is overwritten.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

targetFilePath

STRING

The path to which the zip file is saved. E.g. '/private/save.zip'

Return values
Name Type Description

success

BOOL

True if successfully saved the zip file to the filesystem

Sample
local success = File.Archive.ZIP.save(handle, "/private/save.zip")
serialize()
Short description

Returns the current zip file state as content of a binary buffer. This is useful if the zip file needs to be in memory so that it could be directly used for further processing. E.g. if the zip file content is directly sent to TCPIP client or similar.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

Return values
Name Type Description

archiveBuffer

BINARY

The binary buffer containing the whole archive. The buffer could be empty on error.

Sample
local buffer = File.Archive.ZIP.serialize(handle)
setComment()
Short description

Sets the global archive comment text used for saving/serializing the archive.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

comment

STRING

The comment text which is set on the archive

setCompression()
Short description

Sets the compression level to use for adding/writing new files to the archive. The deflate compression method is used. If not called, the default level is just to store the files without compression. The function can be called between add/write calls to change the compression level used for files. If not called before the last set value is used implicitly. Files, which are loaded from an existing archive, keep their compression and cannot be changed (Need to be removed and added again).

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

complevel

ENUM Compression

The level used for compression

Sample
File.Archive.ZIP.setCompression(handle, "BEST")
setPassword()
Short description

Sets the password used for decryption/encryption during accessing and writing the archive. Only the load/save and deserialize/serialize functions use the current set password. If not called, there is no password used. The password is globally set for all operations for the whole archive content. It is NOT possible to set passwords per file. Also if the to be loaded file uses different passwords per file, it currently isn’t possible to be loaded.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

password

STRING

Sets the password used for accessing and writing the archive. If empty, not password is used.

Sample
File.Archive.ZIP.setPassword(handle, "mypassword")
test()
Short description

Fully tests and verifies the currently loaded archive. Needs some time and fully reads the file. 1. Tests if the set password works with all files 2. Reads all content and verifies their CRC32 checksums 3. Verifies the file infos and the central directory

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

Return values
Name Type Description

valid

BOOL

True if the archive is valid. False if one validation step has failed or no archive is loaded.

write()
Short description

Adds a single file from the specified binary buffer. This is useful if the file is already present in memory so that it does not need to be stored to a file to add it. E.g. if the zip file is directly received from a TCPIP client or similar. If there is already a file or folder with that archive path, it is overwritten.

Parameters
Name Type Description

handle

HANDLE

The instance handle for the ZIP archiver

fileBuffer

BINARY

The binary buffer containing the zip file.

archiveFilePath

STRING

The path in the archive to which the file or directory should be added. Must be a full file path including file name. Sub-directories are created automatically. Existing file is overwritten. E.g. 'archiveFolder/archiveFile.txt'

Return values
Name Type Description

success

BOOL

True if successfully added the file.

Sample
local success = File.Archive.ZIP.write(handle, buffer, "archiveFolder/archiveFile.txt")

Halcon

Short description

Load Halcon procedures or operators and execute them. Native AppSpace input parameters are converted to Halcon types, and Halcon output parameters are converted to native Appspace types. The following conversions are supported: - Strings, floats and integers (correspond to Halcon control parameter tuple) - Vectors of strings, floats and integers (correspond to Halcon control parameter tuples) - Image (correspond to the Halcon iconic type Image) - Shape and Shape.Composite (correspond to the Halcon iconic type XLD) - Image.PixelRegion (correspond to the Halcon iconic type Region) - PointCloud (correspond to Halcon control parameters refering to an ObjectModel3D) - Mesh (correspond to Halcon control parameters refering to an ObjectModel3D with additional attributes 'triangles' and possibly 'point_normal_x', 'point_normal_y' and 'point_normal_z') Features: - A Halcon handle can be reused to load multiple procedures during its lifetime. - Input parameters that do not change between executions only need to be set once. That is, there is no need to call Halcon.setInteger(h, 'YourParam', 10) prior each call to Halcon.execute(h) if that parameter does not change. - Converting single-channel images as input for Halcon uses a shallow copy. Only multi-channel images (RGB) require a deep copy. - Returning images from HALCON always requires a deep copy. Limitation: The scripting engine does not support Halcons protected procedures feature. Please use the read protection property for the application from AppStudio instead. A first example: h = Halcon.create() Halcon.loadProcedure(h, '>sobel_amp') Halcon.setImage(h, 'Image', image) Halcon.setString(h, 'FilterType', 'sum_abs') Halcon.setInteger(h, 'Size', 3) r = Halcon.execute(h) i = Halcon.Result.getImage(r, 'EdgeAmplitude') This will load Halcons Sobel filter, process the input image image and return the result. Accessing Files and Directories: The Halcon scripting interface provides placeholders in order to enable Halcon scripts to access the applications 'resources', 'private' and 'public' folders and if available also storage mounted by usb, sdcard or ram disk. In Halcon, the following set of placeholders are available: - APPDATA_RESOURCES - APPDATA_PRIVATE - APPDATA_PUBLIC - APPDATA_SDCARD (if available) - APPDATA_USB (if available) - APPDATA_RAM (if available) These placeholders can be used within Halcon procedures to read and write data. E.g. the following syntax can be used for reading an OCR classifier: read_ocr_class_mlp(APPDATA_RESOURCES + 'Document_A-Z+_Rej.omc', OCRModel) Please note that these keywords must be used only within the corresponding operator scope. The following is not valid and will yield an error when loading a procedure: Path := APPDATA_RESOURCES + 'Document_A-Z+_Rej.omc' read_ocr_class_mlp(Path, OCRModel) The above syntax is required for all read and write operators in Halcon. The scripting interface restricts the usage of such operators to use one of these placeholders to access any data. Otherwise, the corresponding procedure will not be loaded. The following list of operators performing a read operation can use all placeholders: caltab_points, create_text_model_reader, disp_caltab, file_exists, find_caltab, find_marks_and_pose, get_prep_info_class_gmm, get_prep_info_class_mlp, get_prep_info_class_svm, get_prep_info_ocr_class_mlp, get_prep_info_ocr_class_svm, import_lexicon, list_files, read_aop_knowledge, read_bar_code_model, read_calib_data, read_cam_par, read_camera_setup_model, read_class_box, read_class_gmm, read_class_knn, read_class_mlp, read_class_svm, read_class_train_data, read_component_model, read_contour_xld_arc_info, read_contour_xld_dxf, read_data_code_2d_model, read_deformable_model, read_deformable_surface_model, read_descriptor_model, read_distance_transform_xld, read_fft_optimization_data, read_funct_1d, read_gray_se, read_image, read_kalman, read_matrix, read_measure, read_metrology_model, read_ncc_model, read_object, read_object_model_3d, read_object_model_3d_dxf, read_ocr, read_ocr_class_cnn, read_ocr_class_knn, read_ocr_class_mlp, read_ocr_class_svm, read_ocr_trainf, read_ocr_trainf_names, read_ocr_trainf_names_protected, read_ocr_trainf_select, read_ocv, read_polygon_xld_arc_info, read_polygon_xld_dxf, read_pose, read_region, read_sample_identifier, read_samples_class_gmm, read_samples_class_mlp, read_samples_class_svm, read_sampset, read_sequence, read_shape_model, read_shape_model_3d, read_sheet_of_light_model, read_surface_model, read_template, read_texture_inspection_model, read_training_components, read_tuple, read_variation_model, read_world_file, select_feature_set_trainf_knn, select_feature_set_trainf_mlp, select_feature_set_trainf_mlp_protected, select_feature_set_trainf_svm, select_feature_set_trainf_svm_protected, set_calib_data_calib_object, sim_caltab, trainf_ocr_class_box, trainf_ocr_class_knn, trainf_ocr_class_mlp, trainf_ocr_class_mlp_protected, trainf_ocr_class_svm, trainf_ocr_class_svm_protected, update_kalman The following list of operators performing a write operation can use all placeholders except APPDATA_RESOURCES and can thus not access the applications 'resources' folder: delete_file, gen_caltab, open_file, store_par_knowledge, write_aop_knowledge, write_bar_code_model, write_calib_data, write_cam_par, write_camera_setup_model, write_class_box, write_class_gmm, write_class_knn, write_class_mlp, write_class_svm, write_class_train_data, write_component_model, write_contour_xld_arc_info, write_contour_xld_dxf, write_data_code_2d_model, write_deformable_model, write_deformable_surface_model, write_descriptor_model, write_distance_transform_xld, write_fft_optimization_data, write_funct_1d, write_image, write_lut, write_matrix, write_measure, write_metrology_model, write_ncc_model, write_object, write_object_model_3d, write_ocr, write_ocr_class_knn, write_ocr_class_mlp, write_ocr_class_svm, write_ocr_trainf, write_ocr_trainf_image, write_ocv, write_polygon_xld_arc_info, write_polygon_xld_dxf, write_pose, write_region, write_sample_identifier, write_samples_class_gmm, write_samples_class_mlp, write_samples_class_svm, write_shape_model, write_shape_model_3d, write_sheet_of_light_model, write_surface_model, write_template, write_texture_inspection_model, write_training_components, write_tuple, write_variation_model The following list of operators are not supported and using them within a procedure will yield an error during load time of the procedure: close_framegrabber, close_io_channel, close_io_device, close_serial, close_socket, control_io_channel, control_io_device, control_io_interface, copy_file, get_current_dir, gnuplot_close, gnuplot_open_file, gnuplot_open_pipe, gnuplot_plot_ctrl, gnuplot_plot_funct_1d, gnuplot_plot_image, import, make_dir, open_compute_device, open_framegrabber, open_io_channel, open_io_device, open_serial, open_socket_accept, open_socket_connect, open_textwindow, protect_ocr_trainf, read_char, read_io_channel, read_serial, read_string, receive_data, receive_image, receive_region, receive_serialized_item, receive_tuple, receive_xld, release_all_compute_devices, release_compute_device, remove_dir, send_data, send_image, send_region, send_serialized_item, send_tuple, send_xld, set_io_channel_param, set_io_device_param, socket_accept_connect, system_call, test_access, write_io_channel, write_serial, write_string The following list of operators are allowed but they are executed as no-op: dev_clear_obj, dev_clear_window, dev_close_inspect_ctrl, dev_close_tool, dev_close_window, dev_display, dev_get_preferences, dev_get_system, dev_get_window, dev_inspect_ctrl, dev_map_par, dev_map_prog, dev_map_var, dev_open_dialog, dev_open_file_dialog, dev_open_tool, dev_open_window, dev_set_color, dev_set_colored, dev_set_draw, dev_set_line_width, dev_set_lut, dev_set_paint, dev_set_part, dev_set_preferences, dev_set_shape, dev_set_tool_geometry, dev_set_window, dev_set_window_extents, dev_show_tool, dev_unmap_par, dev_unmap_prog, dev_unmap_var, dev_update_pc, dev_update_time, dev_update_var, dev_update_window

Detailed description

Execute Halcon operators and programs within AppSpace.

Type conversion

When executing Halcon procedures or operators, AppSpace input parameters are converted to their corresponding Halcon types. Similarly, Halcon output parameters are converted to Appspace types. The following conversions are supported:

  • String: Halcon control parameter Tuple of type H_TYPE_STRING

  • Floats: Halcon control parameter Tuple of type H_TYPE_REAL

  • Integers: Halcon control parameter Tuple of type H_TYPE_INT

  • Vectors of strings, floats and integers: Halcon control parameter Tuple of their respective type

  • Image: Halcon iconic parameter of type Image

  • Shape and Shape.Composite: Halcon iconic parameter of type XLD

  • Image.PixelRegion: Halcon iconic parameter of type Region

  • PointCloud: Halcon control parameter Tuple referring to an ObjectModel3D

  • Mesh: Halcon control parameters referring to an ObjectModel3D with additional attributes triangles and possibly point_normal_x, point_normal_y and point_normal_z

Features

  • A Halcon handle can be reused to load multiple procedures during its lifetime.

  • Input parameters that do not change between executions only need to be set once. That is, there is no need to call Halcon.setInteger(proc, 'YourParam', 10) prior each call to Halcon.execute(proc) if that parameter does not change.

  • Converting single-channel images as input for a Halcon procedure uses a shallow copy. Multi-channel images (RGB) require a deep copy.

The scripting engine does not support Halcons protected procedures feature. Please use the read protection property for the application from AppStudio instead.

A first example:

The following sample loads the Halcon operator sobel_amp, processes the input image and returns the result Image edgeAmplitude:

local input = Image.create(128, 128, "UINT8")
-- create a handle for executing a Halcon procedure
local proc = Halcon.create()

-- load procedure and assign input parmeters
proc:loadProcedure(">sobel_amp")
proc:setImage("Image", input)
proc:setString("FilterType", "sum_abs")
proc:setInteger("Size", 3)

-- execute and obtain result image from output object "EdgeAmplitude"
local result = proc:execute()
local edgeAmplitude = result:getImage("EdgeAmplitude")

Accessing Files and Directories:

The Halcon scripting interface provides placeholders in order to enable Halcon scripts to access the applications resources, private and public folders. If available on the device, also storage mounted by usb, sdcard or ram disk is supported. To this end, the following set of placeholders are available to be used in Halcon procedures:

  • APPDATA_RESOURCES access the apps resources/ folder

  • APPDATA_PRIVATE access the apps private/ folder

  • APPDATA_PUBLIC access the shared public/ folder

  • APPDATA_SDCARD access the shared sdcard storage

  • APPDATA_USB access the shared usb storage

  • APPDATA_RAM access the shared volatile memory

These placeholders can be used within Halcon procedures to read and write data. E.g. the following syntax can be used to open an OCR classifier from resources/Classifier.omc of the app:

read_ocr_class_mlp(APPDATA_RESOURCES + 'Classifier.omc', OCRModel)

Please note that these keywords must be used only within the corresponding operator scope. The following is not valid and will yield an error when loading a procedure:

Path := APPDATA_RESOURCES + 'Classifier.omc'
read_ocr_class_mlp(Path, OCRModel)

This syntax is required for all read and write operators in Halcon. The scripting interface restricts the usage of such operators to use one of these placeholders to access any data. Otherwise, the corresponding procedure will not validate during loadProcedure().

Restriction:

The following list of operators performing a read operation can use all placeholders:

caltab_points, create_text_model_reader, disp_caltab, file_exists, find_caltab, find_marks_and_pose, get_prep_info_class_gmm, get_prep_info_class_mlp, get_prep_info_class_svm, get_prep_info_ocr_class_mlp, get_prep_info_ocr_class_svm, import_lexicon, list_files, read_aop_knowledge, read_bar_code_model, read_calib_data, read_cam_par, read_camera_setup_model, read_class_box, read_class_gmm, read_class_knn, read_class_mlp, read_class_svm, read_class_train_data, read_component_model, read_contour_xld_arc_info, read_contour_xld_dxf, read_data_code_2d_model, read_deformable_model, read_deformable_surface_model, read_descriptor_model, read_distance_transform_xld, read_fft_optimization_data, read_funct_1d, read_gray_se, read_image, read_kalman, read_matrix, read_measure, read_metrology_model, read_ncc_model, read_object, read_object_model_3d, read_object_model_3d_dxf, read_ocr, read_ocr_class_cnn, read_ocr_class_knn, read_ocr_class_mlp, read_ocr_class_svm, read_ocr_trainf, read_ocr_trainf_names, read_ocr_trainf_names_protected, read_ocr_trainf_select, read_ocv, read_polygon_xld_arc_info, read_polygon_xld_dxf, read_pose, read_region, read_sample_identifier, read_samples_class_gmm, read_samples_class_mlp, read_samples_class_svm, read_sampset, read_sequence, read_shape_model, read_shape_model_3d, read_sheet_of_light_model, read_surface_model, read_template, read_texture_inspection_model, read_training_components, read_tuple, read_variation_model, read_world_file, select_feature_set_trainf_knn, select_feature_set_trainf_mlp, select_feature_set_trainf_mlp_protected, select_feature_set_trainf_svm, select_feature_set_trainf_svm_protected, set_calib_data_calib_object, sim_caltab, trainf_ocr_class_box, trainf_ocr_class_knn, trainf_ocr_class_mlp, trainf_ocr_class_mlp_protected, trainf_ocr_class_svm, trainf_ocr_class_svm_protected, update_kalman

The following list of operators performing a write operation can use all placeholders except APPDATA_RESOURCES and can thus not access the applications resources/ folder:

delete_file, gen_caltab, open_file, store_par_knowledge, write_aop_knowledge, write_bar_code_model, write_calib_data, write_cam_par, write_camera_setup_model, write_class_box, write_class_gmm, write_class_knn, write_class_mlp, write_class_svm, write_class_train_data, write_component_model, write_contour_xld_arc_info, write_contour_xld_dxf, write_data_code_2d_model, write_deformable_model, write_deformable_surface_model, write_descriptor_model, write_distance_transform_xld, write_fft_optimization_data, write_funct_1d, write_image, write_lut, write_matrix, write_measure, write_metrology_model, write_ncc_model, write_object, write_object_model_3d, write_ocr, write_ocr_class_knn, write_ocr_class_mlp, write_ocr_class_svm, write_ocr_trainf, write_ocr_trainf_image, write_ocv, write_polygon_xld_arc_info, write_polygon_xld_dxf, write_pose, write_region, write_sample_identifier, write_samples_class_gmm, write_samples_class_mlp, write_samples_class_svm, write_shape_model, write_shape_model_3d, write_sheet_of_light_model, write_surface_model, write_template, write_texture_inspection_model, write_training_components, write_tuple, write_variation_model

The following list of operators are not supported and using them within a procedure will yield an error during load time of the procedure:

close_framegrabber, close_io_channel, close_io_device, close_serial, close_socket, control_io_channel, control_io_device, control_io_interface, copy_file, get_current_dir, gnuplot_close, gnuplot_open_file, gnuplot_open_pipe, gnuplot_plot_ctrl, gnuplot_plot_funct_1d, gnuplot_plot_image, import, make_dir, open_compute_device, open_framegrabber, open_io_channel, open_io_device, open_serial, open_socket_accept, open_socket_connect, open_textwindow, protect_ocr_trainf, read_char, read_io_channel, read_serial, read_string, receive_data, receive_image, receive_region, receive_serialized_item, receive_tuple, receive_xld, release_all_compute_devices, release_compute_device, remove_dir, send_data, send_image, send_region, send_serialized_item, send_tuple, send_xld, set_io_channel_param, set_io_device_param, socket_accept_connect, system_call, test_access, write_io_channel, write_serial, write_string

The following list of operators are allowed but they are executed as no-op:

dev_clear_obj, dev_clear_window, dev_close_inspect_ctrl, dev_close_tool, dev_close_window, dev_display, dev_get_preferences, dev_get_system, dev_get_window, dev_inspect_ctrl, dev_map_par, dev_map_prog, dev_map_var, dev_open_dialog, dev_open_file_dialog, dev_open_tool, dev_open_window, dev_set_color, dev_set_colored, dev_set_draw, dev_set_line_width, dev_set_lut, dev_set_paint, dev_set_part, dev_set_preferences, dev_set_shape, dev_set_tool_geometry, dev_set_window, dev_set_window_extents, dev_show_tool, dev_unmap_par, dev_unmap_prog, dev_unmap_var, dev_update_pc, dev_update_time, dev_update_var, dev_update_window

Functions

create()
Short description

Creates a new Halcon handle to load and execute procedures.

Return values
Name Type Description

handle

HANDLE

The Halcon handle

Sample
local halconHdl = Halcon.create()
execute()
Short description

Execute the Halcon loaded Halcon procedure and obtain a handle to the result.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

Return values
Name Type Description

handle

HANDLE

The Halcon result object or nil if the execution failed with an error. Inspect the error log for further information.

Sample
local result = Halcon.execute(halconHdl)
getVersion()
Short description

Query the version of the Halcon runtime.

Return values
Name Type Description

version

STRING

The version of the Halcon runtime. Can be nil if Halcon is not licensed.

Sample
local version = Halcon.getVersion()
loadProcedure()
Short description

Load a Halcon procedure. Can be used to load an internal operator or custom procedures from an .hdvp files. Use the syntax local success = Halcon.loadProcedure(halconHdl, "resources/MyHalconProcedure.hdvp") local success = Halcon.loadProcedure(halconHdl, ">sobel_amp") Procedures can call other custom procedures given that all procedures are loaded in the correct order. That is, load the callee first than caller: func1 = Halcon.create() func1:loadProcedure("resources/func1.hdvp") — if func1 calls func2 then loading will fail here with an error because func2 is not known func2 = Halcon.create() func2:loadProcedure("resources/func2.hdvp") — func2 can call func1 because func1 is now known The supplementary setup and teardown functions can be used to initialize and clear handle based objects within Halcon. This can be used to e.g. to setup a shape model or a code reader and handle the corresponding clear opearator gracefully. This meachanism allows to handle the initialization and destruction of such models separated from the processing. As an example, the setup function could execute the following lines of code: global def tuple DataCodeHandle create_data_code_2d_model ('QR Code', [], [], DataCodeHandle) The corresponding teardown function handles the destruction: global tuple DataCodeHandle clear_data_code_2d_model (DataCodeHandle) The DataCodeHandle is available for processing.

Detailed description

The following syntax can be used to load a Halcon procedure from an .hdvp file or an internal operator:

local success = Halcon.loadProcedure(halconHdl, "resources/MyHalconProcedure.hdvp")
local success = Halcon.loadProcedure(halconHdl, ">sobel_amp")

Procedures can call other custom procedures given that all procedures are loaded in the correct order. That is, load the callee first than caller:

func1 = Halcon.create()
func1:loadProcedure("resources/func1.hdvp") -- if func1 calls func2 then loading will fail here with an error because func2 is not known
func2 = Halcon.create()
func2:loadProcedure("resources/func2.hdvp") -- func2 can call func1 because func1 is now known

The supplementary setup and teardown functions can be used to initialize and clear handle based objects within Halcon. This can be used to e.g. to setup a shape model or a code reader and handle the corresponding clear operation gracefully. This allows to handle the initialization and destruction of such model handles outside of the processing.

As an example, a setup function could execute the following lines of code to create a QR code model:

global def tuple DataCodeHandle
create_data_code_2d_model ('QR Code', [], [], DataCodeHandle)

The corresponding teardown function handles the destruction:

global tuple DataCodeHandle
clear_data_code_2d_model (DataCodeHandle)

The DataCodeHandle is available for processing.

Loading of Halcon program files (.hdev) is not supported.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle

procedureName

STRING

The name of the external procedure files (.hdvp) or internal Halcon procedure prefixed by the '>' character.

setupProcedureName

STRING

Halcon procedure to initialize global variables. This procedure will be executed once at the end of this call. The setup procedure must take no argument an can not return a value. Internal operators are not allowed.

teardownProcedureName

STRING

Halcon procedure to clear global variables. This procedure will be executed once when the handle is either destroyed or a new procedure is loaded. The teardown procedure must take no argument an can not return a value. Internal operators are not allowed.

Return values
Name Type Description

success

BOOL

Returns true if the procedure could be loaded and - if supplied - the setup executed successfully.

Sample
local success = Halcon.loadProcedure(halconHdl, "resources/MyHalconProcedure.hdvp")
setComposite()
Short description

Set an iconic XLD input parameter for the Halcon procedure. The Shape.Composite object will be converted to an XLD object.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle

name

STRING

The name of the iconic input variable to assign.

value

OBJECT Shape.Composite

The value of the iconic XLD input parameter to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name.

Sample
local success = Halcon.setComposite(halconHdl, "CompositeVariableName", composite)
setCompositeArray()
Short description

Set an iconic input parameter for the Halcon procedure of type XLD array object. The Shape.Composite object will be converted to an XLD object.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle

name

STRING

The name of the iconic input variable to assign.

value

OBJECT Shape.Composite

The value of the iconic XLD input parameter to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name.

Sample
local success = Halcon.setCompositeArray(halconHdl, "CompoundArrayVariableName", {composite1, composite2})
setContour()
Short description

Set an iconic XLD input parameter for the Halcon procedure. All shape types will be converted to an XLD object. Conversion for the Line shape is not supported.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle

name

STRING

The name of the iconic input variable to assign.

value

OBJECT Shape

The value of the iconic XLD input parameter to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name.

Sample
local success = Halcon.setContour(halconHdl, "ContourVariableName", contour)
setContourArray()
Short description

Set an iconic input parameter for the Halcon procedure of type XLD array object. All shape types will be converted to an XLD object. Conversion for the Line shape is not supported.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the iconic input variable to assign.

value

OBJECT Shape

The value of the iconic XLDs input parameter to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name.

Sample
local success = Halcon.setContourArray(halconHdl, "ContourArrayVariableName", {contour1, contour2})
setDouble()
Short description

Set a control input parameter for the Halcon procedure of type double

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the control input variable to assign.

value

FLOAT

The value of the control input variable to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name.

Sample
local success = Halcon.setDouble(halconHdl, "DoubleVariableName", 3.14)
setDoubleArray()
Short description

Set a control input parameter for the Halcon procedure of type double array

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the control input variable to assign.

value

FLOAT

The value of the control input variable to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name.

Sample
local success = Halcon.setDoubleArray(halconHdl, "DoubleArrayVariableName", {2.718, math.pi})
setIconicParameter()
Short description

Set an iconic input parameter for the Halcon procedure. Use setImage, setRegion and setContour and their Array variants for type-save versions

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the iconic input variable to assign.

value

OBJECT [API:DataFormat:]

The value of the iconic input variable to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name.

Sample
local success = Halcon.setIconicParameter(halconHdl, "IconicVariableName", Iconic)
setImage()
Short description

Set an iconic input parameter for the Halcon procedure of type Image object. Conversion is supported for the following pixel types: uint8, int8, unit16, int16, int32, real

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the iconic image input parameter to assign.

value

OBJECT Image

The value of the iconic Image input parameter to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name.

Sample
local success = Halcon.setImage(halconHdl, "ImageVariableName", image)
setImageArray()
Short description

Set an iconic input parameter for the Halcon procedure of type Image array object. Conversion is supported for the following pixel types: uint8, int8, unit16, int16, int32, real

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the iconic input variable to assign.

value

OBJECT Image

The value of the iconic Images input parameter to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name.

Sample
local success = Halcon.setImageArray(halconHdl, "ImageArrayVariableName", {image1, image2})
setInteger()
Short description

Set a control input parameter for the Halcon procedure of type integer

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the control input variable to assign.

value

INT

The value of the control input variable to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name.

Sample
local success = Halcon.setInteger(halconHdl, "IntegerVariableName", 42)
setIntegerArray()
Short description

Set a control input parameter for the Halcon procedure of type integer array

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the control input variable to assign.

value

INT

The value of the control input variable to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name.

Sample
local success = Halcon.setIntegerArray(halconHdl, "IntegerArrayVariableName", {1, 2, 3})
setMesh()
Short description

Set a ObjectModel3D as input to a procedure. The Mesh is converted into a ObjectModel3D and the corresponding handle is passed to the procedure as control input parameter with the corresponding name. Important: The ObjectModel3D has to be cleared by calling to the operator 'clear_object_model_3d' eventually.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle

name

STRING

The name of the iconic input variable to assign.

value

OBJECT Mesh

The Mesh to convert to an ObjectModel3D

Return values
Name Type Description

success

BOOL

Returns true unless the object could not be converted or the procedure has no control input variable with the corresponding name.

Sample
local success = Halcon.setMesh(halconHdl, "ObjectModel3D", cloud)
setPointCloud()
Short description

Set a ObjectModel3D as input to a procedure. The PointCloud is converted into a ObjectModel3D and the corresponding handle is passed to the procedure as control input parameter with the corresponding name. Important: The ObjectModel3D has to be cleared by calling to the operator 'clear_object_model_3d' eventually.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle

name

STRING

The name of the iconic input variable to assign.

value

OBJECT PointCloud

The PointCloud to convert to an ObjectModel3D

Return values
Name Type Description

success

BOOL

Returns true unless the object could not be converted or the procedure has no control input variable with the corresponding name.

Sample
local success = Halcon.setPointCloud(halconHdl, "ObjectModel3D", cloud)
setRegion()
Short description

Set an iconic Region input parameter for the Halcon procedure. The Image.PixelRegion will be converted to a Region object.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle

name

STRING

TThe name of the iconic input variable to assign.

value

OBJECT Image.PixelRegion

The value of the iconic region input parameter to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name.

Sample
local success = Halcon.setRegion(halconHdl, "RegionVariableName", region)
setRegionArray()
Short description

Set an iconic input parameter for the Halcon procedure of type Region array object. The Image.PixelRegion will be converted to a Region object.

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the iconic input variable to assign.

value

OBJECT Image.PixelRegion

The value of the iconic Regions input parameter to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name.

Sample
local success = Halcon.setRegionArray(halconHdl, "RegionArrayVariableName", {region1, region2})
setString()
Short description

Set a control input parameter for the Halcon procedure of type string

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the control input variable to assign.

value

STRING

The value of the control input variable to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name.

Sample
local success = Halcon.setString(halconHdl, "StringVariableName", "foo")
setStringArray()
Short description

Set a control input parameter for the Halcon procedure of type string array

Parameters
Name Type Description

handle

HANDLE

The Halcon handle.

name

STRING

The name of the control input variable to assign.

value

STRING

The value of the control input variable to assign.

Return values
Name Type Description

success

BOOL

Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name.

Sample
local success = Halcon.setStringArray(halconHdl, "StringArrayVariableName", {"foo", "bar"})

Halcon.Result

Short description

Obtain results from executed Halcon procedure calls

Functions

getContour()
Short description

Get a contour output parameter from the Halcon procedure result

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable of the Halcon procedure

Return values
Name Type Description

contour

OBJECT Shape.Composite

The return parameter or nil on error

Sample
local contour = Halcon.Result.getContour(halconHdl, "ContourVariableName")
getContourArray()
Short description

Get a contour array output parameter from the Halcon procedure result

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable of the Halcon procedure

Return values
Name Type Description

contours

OBJECT Shape.Composite

The return parameter or nil on error

Sample
local contours = Halcon.Result.getContourArray(halconHdl, "ContourArrayVariableName")
getDouble()
Short description

Get a control output parameter from the Halcon procedure result of type float

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable in the Halcon procedure

Return values
Name Type Description

value

FLOAT

The float value of output variable or nil on error

Sample
local value = Halcon.Result.getDouble(halconHdl, "VariableName")
getDoubleArray()
Short description

Get a control output parameter from the Halcon procedure result of type double array

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the control output variable in the Halcon procedure

Return values
Name Type Description

value

FLOAT

The float array of output variable or nil on error

Sample
local value = Halcon.Result.getDoubleArray(halconHdl, "VariableName")
getIconicParameter()
Short description

Get an iconic output parameter from the Halcon procedure result

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable of the Halcon procedure

Return values
Name Type Description

object

OBJECT [API:DataFormat:]

The return parameter or nil on error

Sample
local image = Halcon.Result.getIconicParameter(halconHdl, "IconicVariableName")
getImage()
Short description

Get an image output parameter from the Halcon procedure result

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable of the Halcon procedure

Return values
Name Type Description

image

OBJECT Image

The return parameter or nil on error

Sample
local image = Halcon.Result.getImage(halconHdl, "ImageVariableName")
getImageArray()
Short description

Get an image array output parameter from the Halcon procedure result

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable of the Halcon procedure

Return values
Name Type Description

images

OBJECT Image

The return parameter or nil on error

Sample
local images = Halcon.Result.getImageArray(halconHdl, "ImageArrayVariableName")
getInteger()
Short description

Get a control output parameter from the Halcon procedure result of type integer

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable in the Halcon procedure

Return values
Name Type Description

value

INT

The integer value of output variable or nil on error

Sample
local value = Halcon.Result.getInteger(halconHdl, "VariableName")
getIntegerArray()
Short description

Get a control output parameter from the Halcon procedure result of type integer array

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the control output variable in the Halcon procedure

Return values
Name Type Description

value

INT

The integer array of output variable or nil on error

Sample
local value = Halcon.Result.getIntegerArray(halconHdl, "VariableName")
getMesh()
Short description

Get a ObjectModel3D output parameter from the Halcon procedure result. The ObjectModel3D is converted into a Mesh. Unless 'doNotFreeObjectModel3D' is set, the corresponding ObjectModel3D is deleted by calling the operator 'clear_object_model_3d' internally. Important: When a procedure returns an ObjectModel3D as an output parameter, calling this function is mandatory in order to avoid a memory leak.

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable of the Halcon procedure

doNotFreeObjectModel3D

BOOL

The name of the output variable of the Halcon procedure

Return values
Name Type Description

mesh

OBJECT Mesh

The return parameter or nil on error

Sample
local mesh = Halcon.Result.getMesh(halconHdl, "ObjectModel3D")
getPointCloud()
Short description

Get a ObjectModel3D output parameter from the Halcon procedure result. The ObjectModel3D is converted into a PointCloud. Unless 'doNotFreeObjectModel3D' is set, the corresponding ObjectModel3D is deleted by calling the operator 'clear_object_model_3d' internally. Important: When a procedure returns an ObjectModel3D as an output parameter, calling this function is mandatory in order to avoid a memory leak.

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable of the Halcon procedure

doNotFreeObjectModel3D

BOOL

The name of the output variable of the Halcon procedure

Return values
Name Type Description

cloud

OBJECT PointCloud

The point cloud of n points or nil on error

normals

OBJECT Matrix

The normals represented as n x 4 matrix if the object model has normal information. The first three columns represent the normal dircetion in x, y, and z. The fourth column is a curvature term that si set to 0. Nil otherwise.

Sample
local cloud = Halcon.Result.getPointCloud(halconHdl, "ObjectModel3D")
getRegion()
Short description

Get a region output parameter from the Halcon procedure result

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable of the Halcon procedure

Return values
Name Type Description

region

OBJECT Image.PixelRegion

The return parameter or nil on error

Sample
local region = Halcon.Result.getRegion(halconHdl, "RegionVariableName")
getRegionArray()
Short description

Get a region array output parameter from the Halcon procedure result

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable of the Halcon procedure

Return values
Name Type Description

regions

OBJECT Image.PixelRegion

The return parameter or nil on error

Sample
local regions = Halcon.Result.getRegionArray(halconHdl, "RegionArrayVariableName")
getString()
Short description

Get a control output parameter from the Halcon procedure result of type string

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the output variable in the Halcon procedure

Return values
Name Type Description

value

STRING

The string value of output variable or nil on error

Sample
local value = Halcon.Result.getString(halconHdl, "VariableName")
getStringArray()
Short description

Get a control output parameter for the Halcon procedure result of type string array

Parameters
Name Type Description

handle

CONST_OBJECT Halcon.Result

The Halcon result handle

name

STRING

The name of the control output variable in the Halcon procedure

Return values
Name Type Description

value

STRING

The string array of output variable or nil on error

Sample
local value = Halcon.Result.getStringArray(halconHdl, "VariableName")

Hash

Short description

Namespace for different kinds of hash algorithms. All algorithms have two usage possibilities depending on the users needs: - calculate()-function: For single calculation of the input data and return of the hash value - Create a handle: For multiple incremental calculations useful if the input data is fragmented There are two result options: - Default is as bytes in a binary buffer - Alternative is as hex-ASCII values in a string

Hash.CRC32

Short description

CRC32 hashing algorithm. To possibilities for usage: - Use the calculate()-function to calculate a single hash - Create a handle: For multiple incremental calculations useful if the input data is fragmented There are two result options: - Default is as bytes in a binary buffer - Alternative is as hex-ASCII values in a string

Functions

calculate()
Short description

Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as byte buffer.

Parameters
Name Type Description

data

BINARY

The input data to calculate the hash

Return values
Name Type Description

hash

BINARY

The hash result as byte buffer with size of 4 bytes

Sample
hash = Hash.CRC32.calculate(buf)
calculateHex()
Short description

Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as hex-ASCII string.

Parameters
Name Type Description

data

BINARY

The input data to calculate the hash

Return values
Name Type Description

hash

STRING

The hash result as hex-ASCII string with size of 8 characters

Sample
hash = Hash.CRC32.calculateHex(buf)
create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
handle = Hash.CRC32.create()
getHashValue()
Short description

Returns the current hash value as byte buffer. The current hash value is based on the data which was added before with calls to the update()-function.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

hash

BINARY

The hash result as byte buffer with size of 4 bytes

Sample
Hash.CRC32.getHashValue(buf)
getHashValueHex()
Short description

Returns the current hash value as hex-ASCII string. The current hash value is based on the data which was added before with calls to the update()-function.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

hashString

STRING

The hash result as hex-ASCII string with size of 8 characters

Sample
Hash.CRC32.getHashValueHex(buf)
update()
Short description

Update the hash object with the specified data. This function can be called multiple times e.g. if not all data is currently available.

Parameters
Name Type Description

handle

HANDLE

The instance to use

data

BINARY

The input data to calculate the hash

Hash.MD5

Short description

MD5 hashing algorithm. To possibilities for usage: - Use the calculate()-function to calculate a single hash - Create a handle: For multiple incremental calculations useful if the input data is fragmented There are two result options: - Default is as bytes in a binary buffer - Alternative is as hex-ASCII values in a string

Functions

calculate()
Short description

Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as byte buffer.

Parameters
Name Type Description

data

BINARY

The input data to calculate the hash

Return values
Name Type Description

hash

BINARY

The hash result as byte buffer with size of 16 bytes

Sample
hash = Hash.MD5.calculate(buf)
calculateHex()
Short description

Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as hex-ASCII string.

Parameters
Name Type Description

data

BINARY

The input data to calculate the hash

Return values
Name Type Description

hash

STRING

The hash result as hex-ASCII string with size of 32 characters

Sample
hash = Hash.MD5.calculateHex(buf)
create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
handle = Hash.MD5.create()
getHashValue()
Short description

Returns the current hash value as byte buffer. The current hash value is based on the data which was added before with calls to the update()-function.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

hash

BINARY

The hash result as byte buffer with size of 16 bytes

Sample
Hash.MD5.getHashValue(buf)
getHashValueHex()
Short description

Returns the current hash value as hex-ASCII string. The current hash value is based on the data which was added before with calls to the update()-function.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

hashString

STRING

The hash result as hex-ASCII string with size of 32 characters

Sample
Hash.MD5.getHashValueHex(buf)
update()
Short description

Update the hash object with the specified data. This function can be called multiple times e.g. if not all data is currently available.

Parameters
Name Type Description

handle

HANDLE

The instance to use

data

BINARY

The input data to calculate the hash

Hash.SHA256

Short description

SHA256 hashing algorithm. To possibilities for usage: - Use the calculate()-function to calculate a single hash - Create a handle: For multiple incremental calculations useful if the input data is fragmented There are two result options: - Default is as bytes in a binary buffer - Alternative is as hex-ASCII values in a string

Functions

calculate()
Short description

Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as byte buffer.

Parameters
Name Type Description

data

BINARY

The input data to calculate the hash

Return values
Name Type Description

hash

BINARY

The hash result as byte buffer with size of 32 bytes

Sample
hash = Hash.SHA256.calculate(buf)
calculateHex()
Short description

Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as hex-ASCII string.

Parameters
Name Type Description

data

BINARY

The input data to calculate the hash

Return values
Name Type Description

hash

STRING

The hash result as hex-ASCII string with size of 64 characters

Sample
hash = Hash.SHA256.calculateHex(buf)
create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
handle = Hash.SHA256.create()
getHashValue()
Short description

Returns the current hash value as byte buffer. The current hash value is based on the data which was added before with calls to the update()-function.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

hash

BINARY

The hash result as byte buffer with size of 32 bytes

Sample
Hash.SHA256.getHashValue(buf)
getHashValueHex()
Short description

Returns the current hash value as hex-ASCII string. The current hash value is based on the data which was added before with calls to the update()-function.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

hashString

STRING

The hash result as hex-ASCII string with size of 64 characters

Sample
Hash.SHA256.getHashValueHex(buf)
update()
Short description

Update the hash object with the specified data. This function can be called multiple times e.g. if not all data is currently available.

Parameters
Name Type Description

handle

HANDLE

The instance to use

data

BINARY

The input data to calculate the hash

Image

Short description

Object for images, height maps, distance maps and similar data sampled on a regularly spaced grid. The samples are referred to as pixels whose values can be represented using different types such as unsigned integers (e.g., uint8, uint16), signed integers (e.g., int8, int16), floats (e.g., float32, float64) or RGB24 (3 times uint8 for the red, green and blue channels). The locations of the regular grid points can be described in physical world units, typically in millimeters, using the so-called image world coordinate system. The image world coordinate system is left-handed and aligned with the image axes, with the x-axis pointing from left to right, and a y-axis pointing from top towards bottom, and the origin at the upper left pixel. As the coordinate system is left-handed, positive rotations are specified clock-wise. The image coordinate system is specified as a world origin coordinate of the upper left pixel (pixel center) and a pixel size (e.g., in millimeters) in the x- and y-dimensions. The image world origin and pixel size are provided as meta data in the Image object. For regular gray scale/reflectance images captured by a 2D camera, the default world origin and pixel size are (0,0) and (1,1) respectively, so that the pixel index and image world coordinate system are the same. For height map and depth maps for which pixel values represent ranges in the physical world, there is also a scale factor available from raw pixel value to a physical world unit (typically millimeter). For compact notation, this scaling factor is referred to as pixel size in the z-dimension, and there is also a corresponding world origin in the z-dimension. The Image object meta data also has a 'missing data' flag that indicates if the value 0 is a reserved number representing the absence of measurement rather than the actual numeric value 0. Algorithms will then try to ignore missing data pixels in calculations instead of using the actual value 0. The missing data flag is only supported for unsigned integer types (uint8, uint16, etc) and not for signed types (int16, float32, etc.)

Overview

abs(), absInplace(), add(), addConstant(), addConstantInplace(), addInplace(), addNoise(), addNoiseInplace(), addPlane(), addPlaneInplace(), adjustOriginZ(), adjustOriginZInplace(), bilateral(), binarize(), binarizeAdaptive(), binarizeCompare(), binarizePlane(), bitShift(), bitShiftInplace(), blur(), canny(), clamp(), clampInplace(), clampPlane(), clampPlaneInplace(), clone(), concatenate(), create(), createFromMemory(), crop(), cropRectify(), cropRegion(), difference(), distanceTransform(), divide(), divideInplace(), drawPixelRegion(), drawPixelRegionInplace(), drawPoint(), drawPointCloud(), drawPointCloudInplace(), drawPointInplace(), drawProfile(), drawProfileInplace(), drawShape(), drawShapeInplace(), drawText(), drawTextInplace(), equalizeHistogram(), extractColumnProfile(), extractProfile(), extractRowProfile(), fillRegion(), fillRegionInplace(), findLineSegments(), findLocalExtrema(), gauss(), getFlatRegion(), getFlatness(), getHeight(), getHistogram(), getMax(), getMean(), getMedian(), getMin(), getMinMax(), getMissingDataFlag(), getMissingDataImage(), getMissingDataRegion(), getOrigin(), getPercentiles(), getPixel(), getPixelSize(), getSize(), getSum(), getType(), getValidDataRegion(), getWidth(), getWorldZ(), growRegion(), houghTransformCircle(), houghTransformExtremaToCircles(), houghTransformExtremaToLines(), houghTransformLine(), inpaint(), invert(), invertInplace(), isEqual(), isWithinBounds(), laplace(), load(), max(), maxInplace(), median(), min(), minInplace(), mirror(), missingDataReduce(), missingDataSetAll(), missingDataSetAllInplace(), missingDataSetSurface(), missingDataSetSurfaceInplace(), morphology(), mosaic(), multiply(), multiplyAddConstant(), multiplyAddConstantInplace(), multiplyConstant(), multiplyConstantInplace(), multiplyInplace(), normalize(), pad(), pow(), powInplace(), renderPlane(), renderPlaneInplace(), renderText(), renderTextInplace(), replace(), replaceInplace(), resize(), resizeScale(), rotate(), rotate90(), save(), setAll(), setColumn(), setColumnProfile(), setMissingDataFlag(), setOrigin(), setOriginZ(), setPixel(), setPixelSize(), setPixelSizeZ(), setRow(), setRowProfile(), sobel(), sobelMagnitude(), splitRGB(), subtract(), subtractInplace(), subtractPlane(), subtractPlaneInplace(), subtractProfile(), subtractProfileInplace(), thin(), threshold(), thresholdCompare(), thresholdPlane(), toGray(), toHSV(), toLab(), toMatrix(), toPixelCoordinate(), toPixelZ(), toPointCloud(), toRGB(), toSquarePixels(), toString(), toType(), toWorldCoordinate(), toWorldZ(), transform(), transformInto(), transformInto3D(), warpSector()

Functions

abs()
Short description

Computes the absolute value of each pixel. Image world coordinate system handling: The operation is not implemented for images with z-origin different from 0.0. The image metadata from the input image is copied to the output image. Missing data handling: There is no special handling of missing data as the value 0 remains 0 after the operation.

Keywords

arithmetic, magnitude, absolute

See also

Image.absInplace

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

Return values
Name Type Description

result

OBJECT Image

The absolute value image.

Sample
result = Image.abs(image)
absInplace()
Short description

Inplace version of the Image.abs function that modifies the input image. See base function for full documentation.

Keywords

arithmetic, magnitude, absolute

See also

Image.abs

Parameters
Name Type Description

image

OBJECT Image

The source image. This image is overwritten with the result image.

Return values
Name Type Description

result

OBJECT Image

A reference to the result image.

Sample
Image.absInplace(image)
add()
Short description

Adds two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.

Keywords

arithmetic, sum

Parameters
Name Type Description

image1

CONST_OBJECT Image

The first source image.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

The sum image.

Sample
result = Image.add(image1, image2)
addConstant()
Short description

Adds a constant value to all pixels in the image. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, the constant is interpreted in image world coordinate units, e.g., millimeters, and is rescaled to a raw pixel value using the z-pixelsize and z-origin of the image. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

arithmetic, level, plus, offset

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

constant

FLOAT

The constant interpreted in image world units (z-origin and z-pixelsize taken into account).

Return values
Name Type Description

result

OBJECT Image

The sum image.

Sample
result = Image.addConstant(image, constant)
addConstantInplace()
Short description

Inplace version of Image.addConstant function which modifies the input image. See base function for full documentation.

Keywords

arithmetic, level, plus, offset

Parameters
Name Type Description

image

OBJECT Image

The source image.

constant

FLOAT

The constant interpreted in image world units (z-origin and z-pixelsize taken into account).

Return values
Name Type Description

resultReference

OBJECT Image

Reference to the sum image.

Sample
Image.addConstantInplace(image, constant)
addInplace()
Short description

Inplace version of the Image.add function which modifies the first input image to contain the sum of the input images. See base function for full documentation.

Keywords

arithmetic, sum

Parameters
Name Type Description

image1

OBJECT Image

The first source image. This image is overwritten with the sum.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.addInplace(image1, image2)
addNoise()
Short description

Adds a uniform noise value in the range [a,b] to all pixels in the image. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a heightmap, distance or range image, the noise interval parameters [a,b] are interpreted in image world coordinate units, e.g., millimeters, and is rescaled to a raw pixel value using the z-pixelsize and z-origin of the image. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

random, uniform, white

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

a

FLOAT

Lower interval limit interpreted in image world units (z-origin and z-pixelsize taken into account).

b

FLOAT

Upper interval limit interpreted in image world units (z-origin and z-pixelsize taken into account).

randSeed

INT

Random seed, optional. Default value is 0.

Return values
Name Type Description

result

OBJECT Image

The result image.

Sample
result = Image.addNoise(image, 10, 100, 0)
addNoiseInplace()
Short description

Inplace version of the Image.addNoise function that modifies the input image. See base function for full documentation.

Keywords

random, uniform, white

See also

Image.addNoise

Parameters
Name Type Description

image

OBJECT Image

The source image. This image is overwritten with the result image.

a

FLOAT

Lower interval limit interpreted in image world units (z-origin and z-pixelsize taken into account).

b

FLOAT

Upper interval limit interpreted in image world units (z-origin and z-pixelsize taken into account).

randSeed

INT

Random seed, optional. Default value is 0.

Return values
Name Type Description

resultReference

OBJECT Image

A reference to the result image.

Sample
Image.addNoiseInplace(image, 10, 100, 0)
addPlane()
Short description

Adds the value of a plane function (Shape3D) to every pixel in an image. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. Image world coordinate system handling: The plane is interpreted in world space and added to the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

gradient, ramp

Parameters
Name Type Description

image

CONST_OBJECT Image

The image.

plane

CONST_OBJECT Shape3D

The plane to add, must be a Shape3D plane.

region

CONST_OBJECT Image.PixelRegion

Region of the image where the plane should be added, default is the full image. An empty region or nil are interpreted as the full image.

Return values
Name Type Description

resultImage

OBJECT Image

The image with the added plane. Nil if an error occurred.

Sample
resultImage = Image.addPlane(image, plane, region)
addPlaneInplace()
Short description

Inplace version of the Image.addPlane function which modifies the input image by adding the value of a given plane. See base function for full documentation.

Keywords

gradient, ramp

Parameters
Name Type Description

image

OBJECT Image

The image. This image is overwritten with the result image.

plane

CONST_OBJECT Shape3D

The plane to add, must be a Shape3D plane.

region

CONST_OBJECT Image.PixelRegion

Region of the image where the plane should be added, default is the full image. An empty region or nil are interpreted as the full image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.addPlaneInplace(image, plane, region)
adjustOriginZ()
Short description

Adjusts the image z-origin to the given value in world coordinates, changing the raw pixel values such that the represented world coordinate values stays the same. Adjusting the z-origin to -10.0 will allow unsigned types to represent world-coordinate values from -10.0 and larger. Pixel values outside the range of the image type will be clamped. To set a new origin without changing the raw pixel values, offsetting the world coordinate values, see Image.setOriginZ. Image world coordinate system handling: The operation keeps pixel values in the world coordinate system constant, unless underflow or overflow occurs. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Parameters
Name Type Description

image

CONST_OBJECT Image

The input image image.

newOriginZ

FLOAT

New origin in z-direction for image.

Return values
Name Type Description

resultImage

OBJECT Image

The image with the adjusted origin. Nil if an error occurred.

Sample
resultImage = Image.adjustOriginZ(image, newOriginZ)
adjustOriginZInplace()
Short description

Inplace version of the Image.adjustOriginZ function that modifies the input image. See base function for full documentation.

Parameters
Name Type Description

image

OBJECT Image

The input image image.

newOriginZ

FLOAT

New origin in z-direction for image.

Return values
Name Type Description

resultImage

OBJECT Image

The image with the adjusted origin. Nil if an error occurred.

Sample
resultImage = Image.adjustOriginZInplace(image, newOriginZ)
bilateral()
Short description

Applies a bilateral filter to an image. The bilateral filter is similar to a Gauss filter but it also adaptively modifies the filter kernel to avoid smoothing over image boundaries. Image world coordinate system handling: The kernel size in the range/z-dimension is interpreted in world scale, e.g., millimeters, it is internally divided by the z-pixelsize to get raw pixel value thresholds. The output image inherits the image world coordinates. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.

Keywords

edge preserving, filter, gauss, sigma, denoise

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, float32 and rgb24.

kernelSizeSpatialPix

INT

Size of the kernel in pixels, must be positive and odd.

kernelSizeRange

FLOAT

Range of intensity values that affect the filtering, must be positive.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined.

Return values
Name Type Description

filteredImage

OBJECT Image

Filtered image

Sample
filteredImage = Image.bilateral(image, kernelSizeSpatialPix, kernelSizeRange)
binarize()
Short description

Applies a threshold interval (lowerThreshold, upperThreshold) to the image to create a binary image. It is possible to binarize only a specified region. This function produces an image output, to directly produce a PixelRegion output use the threshold() function instead. Image world coordinate system handling: The input threshold values are interpreted in image world coordinates, i.e., they are converted to raw pixel thresholds within the function using the z-origin and z-pixelsize. As the output image is binary the output z-origin is set to 0 and the z-pixelsize to 1. The output image inherits the image world coordinates in the xy-dimensions. Missing data handling: Missing data pixels are set to background, i.e., to 0 in the output image. The output image has its missing data flag turned off regardless of the flag of the input image.

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32 and float64.

lowerThreshold

FLOAT

Lower threshold for the binarization in image world coordinates, i.e., the z-pixel size and origin are used so that the threshold is interpreted in millimeters in case the image is a height map/distance/range image.

upperThreshold

FLOAT

Upper threshold for the binarization in world coordinates. Optional, defaults to max value of the pixel type.

outputValue

INT

Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest to consider when binarizing, values outside are set to zero.

Return values
Name Type Description

binarizedImage

OBJECT Image

Binarized image of pixel type uint8.

Sample
thresholdImage = Image.binarize(image, lowerThreshold, upperThreshold, outputValue, region)
binarizeAdaptive()
Short description

Applies an adaptive filter to the image to create a binary image. A pixel is set in the binary output image if the value is significantly larger than the average value in a surrounding region of specified size. The threshold is set as a delta value how much larger the pixel value must be in world coordinates, i.e, the delta threshold value is scaled internally with the pixel size in the z-dimension. In its base form, bright objects on dark background are found. There is a parameter to instead find dark objects on a bright background.

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image, currently only uint8 format is supported.

deltaThresholdWorld

FLOAT

Threshold value, all pixels with a value higher than the mean in the surrounding region plus this threshold is set to outputValue

kernelSizePix

INT

Size of the kernel in number of pixels, must be odd and greater than one.

findBright

BOOL

Set to true to find bright objects on dark background. Set to false to find dark objects on a bright background. Optional, default is true.

outputValue

INT

Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.

Return values
Name Type Description

binarizedImage

OBJECT Image

Adaptively binarized image.

Sample
filteredImage = Image.binarizeAdaptive(image, deltaThresholdWorld, kernelSizePix, findBright, outputValue, region)
binarizeCompare()
Short description

Binarizes an image by pixelwise comparison with a reference image. All pixels with a value greater than or equal to the corresponding reference image value are included in the binary output image. An optional margin (positive or negative) may be provided, adjusting the reference image values prior to the comparison. A larger positive margin results in fewer included pixels. The optional flag findBright may be set to false, returning the region where the image is lower/darker than the reference image. A region of interest can be provided, limiting the processing to that region. The images must be of the same pixel type and be of equal size. This function gives an Image object as output, to get a PixelRegion output use thresholdCompare instead. Image world coordinate system handling: To allow for an efficient comparison, the z-pixelsizes of the input images must be equal but the z-offsets may differ. The margin parameter is interpreted in image world coordinates, e.g., as a millimeter margin if the input is a range image. The output image inherits x,y-origin and x,y-pixelsizes but the z-origin is set to 0 and z-pixelsize to 1. Missing data handling: Missing data pixels are excluded from the output.

Keywords

adaptive, background, foreground, segmentation

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image to binarize.

referenceImage

CONST_OBJECT Image

Reference image to compare the input image with.

marginWorld

FLOAT

Optional offset of the reference image. Default value is 0.

findBright

BOOL

Optional flag indicating if pixels brighter/higher or darker/lower than the reference image should be included. Default is true, returning brighter pixels.

outputValue

FLOAT

Optional value for pixels in the output image mask, default 255.

regionOfInterest

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. The default region is the entire image.

Return values
Name Type Description

maskImage

OBJECT Image

Image containing all pixels passing the comparison operation.

Sample
maskImage = Image.binarizeCompare(image, referenceImage, marginWorld, findBright, outputValue, regionOfInterest)
binarizePlane()
Short description

Applies a threshold interval (lowerThreshold, upperThreshold) relative to the given plane to create a binary image from a height map. The threshold values accounts for world coordinates (pixel size and origin in the z-dimension) if applicable. It is possible to binarize only a specified region. The thresholds may both be negative or positive, allowing selecting values strictly below or above the reference. This function produces an image output, to directly produce a PixelRegion output use the thresholdPlane function instead. Image world coordinate system handling: The plane is interpreted in world space which is compared with the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the output image mask has the same pixel size and origin in x,y as the input image. Along the value axis z, the pixel size and origin are reset to unit and zero respectively. Missing data handling: No pixels marked as missing are included in the output mask. The missing data flag of the output mask image is cleared.

Keywords

adaptive, background, foreground, segmentation, binarize

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, uint32, int8, int16, int32, float32 and float64.

lowerThreshold

FLOAT

Lower threshold for the binarization in image world coordinates, i.e., the z-pixel size and origin are used so that the threshold is interpreted in millimeters in case the image is a height map/distance/range image.

upperThreshold

FLOAT

Upper threshold for the binarization in world coordinates.

plane

CONST_OBJECT Shape3D

The plane to which the lower and upper thresholds are related. The shape should be a plane.

outputValue

INT

Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest to consider when binarizing, values outside are set to zero.

Return values
Name Type Description

binaryImage

OBJECT Image

Binarized image of pixel type uint8.

Sample
binaryImage = Image.binarizePlane(image, lowerThreshold, upperThreshold, plane, outputValue, region)
bitShift()
Short description

Bit shifts all pixel values in an image of unsigned integer type. This is a fast way of multiplying or dividing (integer division) image values with powers of two. Negative shift length is used for division. Note that there are no overflow or underflow checks for this operation! The operation is performed correctly both for raw pixel values and world pixel values. There is a slight difference when shifting using positive values compared to a real multiplication when going out of bounds. The bitshift operation simply drops the most significant bit. For an image of uint8 and a pixel value of 255 this would mean that shifting once with a positive value would shift in one zero and thus producing a lower value than before (254). Ex. 1111 1111 << 0 (uint8 255) 1111 1110 << 0 (uint8 254) 1111 1100 (uint8 252) As can be seen the behavior is not the ideal once the limit of the data type is reached. To avoid this problem use a sufficiently large image data type, or to get the a saturating behavior, see Image.multiplyConstant. Image world coordinate system handling: If the image has a non-zero z-origin, the z-origin of the returned image is adjusted in order to keep the operation valid both for raw- and world pixels. All other origin values and all pixel sizes are respected and copied to the returned image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, additional pixels may be marked as missing.

Keywords

arithmetic, divide, scale, multiply

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

shifts

INT

The shift length in number of bits, each positive shift corresponds to multiplying with two. Each negative shift corresponds to division with two.

Return values
Name Type Description

result

OBJECT Image

The bit-shifted image.

Sample
result = Image.bitShift(image, shifts)
bitShiftInplace()
Short description

Inplace version of Image.bitShift function which modifies the input image. See base function for full documentation.

Keywords

arithmetic, divide, multiply

Parameters
Name Type Description

image

OBJECT Image

The source image. This image is overwritten with the result image.

shifts

INT

The shift length in number of bits, each positive shift corresponds to multiplying with two. Each negative shift corresponds to division with two.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.bitShiftInplace(image, shifts)
blur()
Short description

Blurs an image using a constant normalized box filter kernel. Image world coordinate system handling: The box filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.

Keywords

box, boxcar, convolve, denoise, filter, smooth

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, int16, float32 and float64.

kernelSizePix

INT

Size of the kernel, must be positive.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined.

fillMissingData

BOOL

Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false.

Return values
Name Type Description

smoothImage

OBJECT Image

Output image blurred by the blur filter. Same type as input image.

Sample
smoothImage = Image.blur(image, kernelSizePix)
canny()
Short description

Applies Canny edge detection to find edges in an image. The Canny edge detection works with a dual threshold procedure: first strong edges are found using a high threshold value. A second lower threshold also detects weaker edges in the image, and the weaker edges that are connected with the stronger edges are kept in the output edge image. A non-maximum suppression operation is also applied to obtain 1-pixel wide edge responses. The Canny function currently only operates on uint8 images. Image world coordinate system handling: The input thresholds are interpreted in world scale, e.g., millimeters, they are internally divided by the z-pixelsize to get raw pixel value thresholds. The output image inherits the image world coordinates in the x,y-dimensions, but the z-pixelsize is set to 1 and the z-origin to 0. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.

Keywords

derivative, gradient, edge

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Currently only uint8 pixel type is supported.

thresholdHigh

FLOAT

First/high threshold to find strong edges, for example a value of 100.

thresholdLow

FLOAT

Second/low threshold for finding weaker edges connected with the strong edges, for example a value of 50.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined.

Return values
Name Type Description

cannyImage

OBJECT Image

Output image.

Sample
cannyImage = Image.canny(image, thresholdHigh, thresholdLow)
clamp()
Short description

Clamps the pixel values to an interval [maxValue, minValue]. An optional region may be provided, limiting the processing to only that region. Pixels outside the region are left in an undefined state. Image world coordinate system handling: The [maxValue, minValue] parameters are interpreted as expressed in image world coordinate units, i.e., the clamp limits are scaled internally from world (millimeter) units to raw pixel values using the origin and pixelsize in the z-dimension. The image metadata from the input image is copied to the output image. Missing data handling: A missing data pixel in the input image results in a missing data pixel in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image. Setting the optional fillMissingData flag, missing data pixels will be set to the minimum clamp value. If this flag is set, the output image will have its missing data flag cleared.

Keywords

arithmetic, limit, clip

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

minValueWorld

FLOAT

The minimum value to clamp to interpreted in image world units (z-origin and z-pixelsize taken into account).

maxValueWorld

FLOAT

The maximum value to clamp to in image world units (z-origin and z-pixelsize taken into account).

region

CONST_OBJECT Image.PixelRegion

Optional region to process. Default is the entire image.

fillMissingData

BOOL

Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false.

Return values
Name Type Description

result

OBJECT Image

The clamped image.

Sample
result = Image.clamp(image, minValue, maxValue, region, fillMissingData)
clampInplace()
Short description

Inplace version of the Image.clamp function that modifies the input image. See base function for full documentation.

Keywords

arithmetic, limit, clip

Parameters
Name Type Description

image

OBJECT Image

The source image. This image is overwritten with the result image.

minValueWorld

FLOAT

The minimum value to clamp to interpreted in image world units (z-origin and z-pixelsize taken into account).

maxValueWorld

FLOAT

The maximum value to clamp to in image world units (z-origin and z-pixelsize taken into account).

region

CONST_OBJECT Image.PixelRegion

Optional region to process. Default is the entire image.

fillMissingData

BOOL

Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.clampInplace(image, minValue, maxValue, region, fillMissingData)
clampPlane()
Short description

Clamps image pixel values to a plane from below, i.e., values are raised to the plane. In case of overflow, the value is instead clamped to the maximal representable value. A partial region of operation may be selected, reducing the processing time. All pixels outside the region are left in an undefined state. Image world coordinate system handling: The plane is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: By default, a missing data pixel in the input image generates a missing data pixel in the output image. If the fillMissingData flag is set to true, all pixels with missing data will be set to the plane value and the missing data flag of the output image will be cleared. In that case, the full range of raw pixel values may be used.

Keywords

limit, clip

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to clamp.

plane

CONST_OBJECT Shape3D

The plane to clamp to, must be a Shape3D plane.

region

CONST_OBJECT Image.PixelRegion

Optional region where clamping should be performed, default is the full image. An empty region or nil are interpreted as the full image.

fillMissingData

BOOL

Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false.

Return values
Name Type Description

clampedImage

OBJECT Image

The clamped image. Nil if an error occurred.

Sample
clampedImage = Image.clampPlane(image, plane, region, fillMissingData)
clampPlaneInplace()
Short description

Inplace version of the Image.clampPlane function that modifies the input image. See base function for full documentation.

Keywords

limit, clip

Parameters
Name Type Description

image

OBJECT Image

The image to clamp. This image is overwritten with the result image.

plane

CONST_OBJECT Shape3D

The plane to clamp to, must be a Shape3D plane.

region

CONST_OBJECT Image.PixelRegion

Optional region where clamping should be performed, default is the full image. An empty region or nil are interpreted as the full image.

fillMissingData

BOOL

Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.clampPlaneInplace(image, plane, region, fillMissingData)
clone()
Short description

Returns a duplicated instance of the input image. New memory to copy all pixel data is allocated.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to clone.

Return values
Name Type Description

clone

OBJECT Image

The new cloned image object.

Sample
local imageClone = Image.clone(image)
concatenate()
Short description

Concatenates two images. Image world coordinate system handling: The image world coordinate system is used to update the output image origin. The new origin depends on how image2 is placed in relation to image1 (direction), the different possibilities are: - ABOVE (Oxout, Oyout, Ozout) = (Oximage1, Oyimage1-image2Height*image2PixelSizeY, Ozimage1) - BELOW (Oxout, Oyout, Ozout) = (Oximage1, Oyimage1, Ozimage1) - RIGHT (Oxout, Oyout, Ozout) = (Oximage1, Oyimage1, Ozimage1) - LEFT (Oxout, Oyout, Ozout) = (Oximage1-image2Width*image2PixelSizeX, Oyimage1, Ozimage1) Both input images must have the same pixel size, inherited by the output image. Missing data handling: The output image missing data flag is inherited from image1.

Keywords

union, join

See also

Image.pad

Parameters
Name Type Description

image1

CONST_OBJECT Image

The first image.

image2

CONST_OBJECT Image

The second image.

direction

ENUM ConcatenationDirection

The direction of the concatenation, i.e. where to place image2 in relation to image1, default is to the right of image1.

Return values
Name Type Description

imageOut

OBJECT Image

The concatenated image.

Sample
local imageOut = Image.concatenate(image1, image2, 1)
create()
Short description

Creates a new image of a certain size and pixel type.

Parameters
Name Type Description

width

INT

The image width in pixels.

height

INT

The image height in pixels.

type

ENUM ImageType

The pixel type, for example UINT8, INT16, FLOAT64.

Return values
Name Type Description

image

OBJECT Image

The new image object.

Sample
local image = Image.create(800,600,"UINT8")
createFromMemory()
Short description

Creates a new image of a certain size and pixel type by copying the data of a binary buffer.

Parameters
Name Type Description

buffer

BINARY

The buffer containing the raw image data.

width

INT

The image width in pixels.

height

INT

The image height in pixels.

type

ENUM ImageType

The pixel type, for example UINT8, INT16, FLOAT64.

Return values
Name Type Description

image

OBJECT Image

The new image object.

Sample
local image = Image.createFromMemory(buffer,800,600,"UINT8")
crop()
Short description

Crops a subpart of an image, specified in pixel coordinates. A cropped image is a clone of the source data.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to crop.

x

INT

The x position of the top-left corner of the cropped image in the source image.

y

INT

The y position of the top-left corner of the cropped image in the source image.

width

INT

The width of the cropped image.

height

INT

The height of the cropped image.

Return values
Name Type Description

imageCropped

OBJECT Image

Cropped image or nil on error.

Sample
local imageCropped = Image.crop(fullImage, 10, 10, 100, 100)
cropRectify()
Short description

Crops the region defined by a rotated rectangle or a closed polyline, and also rotates/transforms the cropped image patch to become axis-aligned using a linear interpolation operation. The size of the output image is determined automatically to obtain approximately the same pixel resolution as the input image has. If the crop region extends outside the input image borders, the corresponding pixels in the output image get the value 0. For a Shape Rectangle type region input, the function crops and rotates the content within the rectangle to a new image. The rotation of the input rectangle is reversed so that the output is defined by a zero-degree-rotated rectangle with the same width and height as the input rectangle. For a Shape Polyline type region input, it is a requirement that the polyline has exactly 4 points and that it encloses a convex region, e.g., it must not self-intersect. The function then crops the defined region and applies a homography transform to transform the content into an axis-aligned bounding box. The order of the four points in the polyline is relevant. The following mapping from points in the polyline to corners in the output image patch is made: - 1st point maps to upper left corner - 2nd point maps to upper right corner - 3rd point maps to lower right corner - 4th point maps to lower left corner. The transform from the input shape (Rectangle or Polyline region) and the output image is also provided. With this transform it is possible to map features, e.g., points, from the input image to the cropped image, and vice versa with the inverse of the transform. The transform is of rigid type when possible and of homography type otherwise. Image world coordinate system handling: New x,y pixel sizes are calculated, based on the input shape and input image. For example, a 90 degree rotated rectangle as a shape would just swap the pixel sizes in x and y in the output image. For non-rectangular shapes the average pixel sizes in the x,y-dimensions are used. Missing-data handling: For images with the missing data flag set, missing data aware sampling will be used and the output image will also set its missing data flag. Values being sampled outside of the image will get the value 0.

Keywords

align, box, homography, rectangle, rotate, transform, warp, cut

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to crop.

shape

CONST_OBJECT Shape

Input Shape defining the region to crop. Must either be of Rectangle type or of Polyline type with 4 points enclosing a convex region with an area greater than 1.

Return values
Name Type Description

imageCropped

OBJECT Image

Cropped and rectified image.

transform

OBJECT Transform

Transformation from the input shape to the new image. The transform is of rigid type for a Rectangle shape input and of homography type otherwise.

Sample
imageCropped, transform = Image.cropRectify(image, shape)
cropRegion()
Short description

Crops the region defined by the bounding box of an input pixelregion. Optionally, padding around the bounding box can also be specified in order to extend it. The pixelregion bounding box is defined by the limits of its non-empty pixels. The output cropped pixelregion is a copy of the region corresponding to the padded pixelregion bounding box (crop region). The cropped image contains a copy of the values inside the crop region. The image size is equal to the size of the crop region, the pixel size is the same as the input image and the image origin value is equal to the top left corner of the crop region. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the origin changes to the value of the top left corner of the crop region. Missing-data handling: The missing data information is kept from the input image.

Keywords

bounding box, cut

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to crop

region

CONST_OBJECT Image.PixelRegion

Input region to crop around. The crop region is defined by the bounding box of the region.

paddingPix

INT

How much padding around the bounding box of the region that should be added in pixels. Optional, default value is 0.

Return values
Name Type Description

imageCropped

OBJECT Image

The cropped image. Returns nil if the input padded pixelregion bounding box is not contained inside the input image.

regionCropped

OBJECT Image.PixelRegion

The region corresponding to the input pixelregion bounding box plus padding if used. Returns nil if the input padded pixelregion bounding box is not contained inside the input image.

Sample
imageCropped, regionCropped = Image.cropRegion(image, region)
difference()
Short description

Computes the pixel-wise difference between two images, using a configurable difference operator. The images must be of equal size and pixel type, and have the same pixel size and origin in the z-dimension. Difference operators: ABS: Absolute difference, |image1 - image2|. SQUARE: Squared difference, (image1 - image2)^2. Return image type: The return image type for all integer image types is unsigned. For SQUARE difference operator, a larger integer type is returned, e.g. UINT16 if the input is INT8. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.

Keywords

arithmetic, minus, subtract

Parameters
Name Type Description

image1

CONST_OBJECT Image

The first source image.

image2

CONST_OBJECT Image

The second source image.

differenceMode

ENUM DifferenceMode

The type of difference operator to be used. Default is ABS.

Return values
Name Type Description

result

OBJECT Image

The difference image.

Sample
result = Image.difference(image1, image2, "SQUARE")
distanceTransform()
Short description

Applies the distance transform operation on the input image. Each pixel in the output image gives the approximate Euclidean distance to the closest background pixel (value = 0) in the input image. Typically the input image is a binarized image with 0:s representing the background and some other value (e.g. 1 or 255) representing the foreground. Currently only the uint8 pixel type is supported. Image world coordinate system handling: The image world coordinate system is not considered in this function. The distances in the output image are in pixel units, i.e., not scaled with the world pixel sizes in x and y. The output image inherits the image world coordinate system of the input image in the x,y dimensions, but the z-origin is set to 0 and the z-pixelsize is set to 1 regardless of the input values. Missing data handling: The function does not consider the missing data flag of the input image. The missing data flag of the output will be set to false, i.e., no missing data.

Keywords

chamfer, manhattan, skeleton, euclidian

See also

Image.thin

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image, expected to be binary. Only uint8 type supported.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined.

Return values
Name Type Description

distanceImage

OBJECT Image

Distance image with approximate Euclidean distance values, float32 type.

Sample
distanceImage = Image.distanceTransform(image)
divide()
Short description

Divides two images pixelwise. The images must be of equal size and pixel type. A division-by-zero leads to a 0 in the output image. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate value. The second image is treated as a unit-less modifier and it must therefore have a standard image world coordinate system with pixel sizes all equal to 1 and origins equal to 0. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. Note that it is possible to obtain 0 as result of the division and that such pixels then will be considered as missing data in subsequent processing steps.

Keywords

arithmetic, ratio

Parameters
Name Type Description

image1

CONST_OBJECT Image

The first source image.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

The quotient image.

Sample
result = Image.divide(image1, image2)
divideInplace()
Short description

Inplace version of the Image.divide function which modifies the first input image to contain the ratio of the input images. See base function for full documentation.

Keywords

arithmetic, ratio

See also

Image.divide

Parameters
Name Type Description

image1

OBJECT Image

The first source image. This image is overwritten with the image ratio.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.divideInplace(image1, image2)
drawPixelRegion()
Short description

Render one or several PixelRegions into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The View.PixelRegionDecoration object is used to set the color of the rendered regions. Image world coordinate system handling: The input PixelRegion is interpreted in raw pixel coordinates, the image world coordinate system is not considered. Missing data handling: This function does not use the missing data flag.

Keywords

display, fill, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to render the region(s) into. Supported image types are UINT8 and RGB.

regions

CONST_OBJECT Image.PixelRegion

The region(s) that are to be rendered in the image.

decoration

CONST_OBJECT View.PixelRegionDecoration

A decorator that describes how the region(s) are to be rendered.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay.

Sample
image = Image.drawPixelRegion(image, regions, decoration)
drawPixelRegionInplace()
Short description

Inplace version of the Image.drawPixelRegion function which modifies the input image. See base function for full documentation.

Keywords

display, fill, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

OBJECT Image

The image to render the region(s) into. Supported image type is RGB.

shapes

CONST_OBJECT Image.PixelRegion

The region(s) that are to be rendered in the image.

decoration

CONST_OBJECT View.PixelRegionDecoration

A decorator that describes how the region(s) are to be rendered.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay. Reference to input image.

Sample
image = Image.drawPixelRegionInplace(image, regions, decoration)
drawPoint()
Short description

Render the position of one or several points into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. to RGB. The View.ShapeDecoration object is used to set graphical properties. The following parameters in the ShapeDecoration object are supported: - The LineColor property is used to set the color of the points. - The PointType property is used to render points as circles or crosses. - The PointSize property is used to set the size of the rendered points. Image world coordinate system handling: The points coordinates are interpreted as world coordinates. That is, the coordinate system of the image is used to place the points properly. Missing data handling: This function does not use the missing data flag.

Keywords

display, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to render the point(s) into. Supported image types are UINT8 and RGB.

points

CONST_OBJECT Point

The points (2D) that are to be rendered in the image.

decoration

CONST_OBJECT View.ShapeDecoration

A decorator that describes how the point(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay.

Sample
image = Image.drawPoint(image, points, decoration)
drawPointCloud()
Short description

Render one or several pointclouds into an image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The x- and y- coordinates of each point in the pointcloud are used to place each point into the image world coordinate system. Points are rendered using the information in the PointCloudDecoration object. The following properties in the PointCloudDecoration object are supported: - The ZRange or IntensityRange parameters: If there is a ZRange set, the colors of the rendered points will be based on the z-values. Otherwise the intensity component of each point is used, either using the IntensityRange parameter or using the default range for intensity colors which is 0 to 1. - The PointSize parameter. Image world coordinate system handling: The world coordinate system of the image if respected and each point in the pointcloud is drawn at the corresponding image position. Missing data handling: This function does not use the missing data flag.

Keywords

display, fill, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to render the point clouds(s) into. Supported image types are UINT8 and RGB.

pointcloud

CONST_OBJECT PointCloud

The point clouds(s) that are to be rendered in the image.

decoration

CONST_OBJECT View.PointCloudDecoration

A decorator that describes how the point clouds(s) are to be rendered. Not all properties of the PointCloudDecoration object are supported, see the main function description.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay.

Sample
image = Image.drawPointCloud(image, pointcloud, decoration)
drawPointCloudInplace()
Short description

Inplace version of the Image.drawPointCloud function which modifies the input image. See base function for full documentation.

Keywords

display, fill, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

OBJECT Image

The image to render the point clouds(s) into. Supported image type is RGB.

pointcloud

CONST_OBJECT PointCloud

The point clouds(s) that are to be rendered in the image.

decoration

CONST_OBJECT View.PointCloudDecoration

A decorator that describes how the point clouds(s) are to be rendered. Not all properties of the PointCloudDecoration object are supported, see the main function description.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay.

Sample
image = Image.drawPointCloudInplace(image, pointcloud, decoration)
drawPointInplace()
Short description

Inplace version of the Image.drawPoint function which modifies the input image. See base function for full documentation.

Keywords

display, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

OBJECT Image

The image to render the point(s) into. Supported image type is RGB.

points

CONST_OBJECT Point

The points (2D) that are to be rendered in the image.

decoration

CONST_OBJECT View.ShapeDecoration

A decorator that describes how the point(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay. Reference to input image.

Sample
image = Image.drawPointInplace(image, points, decoration)
drawProfile()
Short description

Render one or several profiles into an image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. For profiles with 1D coordinates the coordinate vector is mapped to the x-axis of the image and the value vector to the y-axis. Each sample in the profile is then drawn in the image world coordinate system. For profiles with 2D coordinates the value vector is discarded and the profile is drawn on its coordinates in the image world coordinate system. Note: This function differs from the View.addProfile function in that it does not provide the full graph plotting functionality as a dedicated graph viewer does, e.g., coordinate axes, background grids etc. are not rendered with the drawProfile function. Color and line width properties are controlled using the View.GraphDecoration object. The two properties used for this are the GraphColor and DrawSize properties in the GraphDecoration object. No other properties in the GraphDecoration are currently supported. Image world coordinate system handling: The world coordinate system of the image if respected and each profile is drawn at the corresponding image position. Missing data handling: This function does not use the missing data flag.

Keywords

display, fill, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to render the profile(s) into. Supported image types are UINT8 and RGB.

profiles

CONST_OBJECT Profile

The profile(s) that are to be rendered in the image.

decoration

CONST_OBJECT View.GraphDecoration

A decorator that describes how the profiles(s) are to be rendered. The DrawSize (line width) and GraphColor (line color) properties are supported.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay.

Sample
image = Image.drawProfile(image, profiles, decoration)
drawProfileInplace()
Short description

Inplace version of the Image.drawProfile function which modifies the input image. See base function for full documentation.

Keywords

display, fill, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

OBJECT Image

The image to render the profile(s) into. Supported image type is RGB.

profiles

CONST_OBJECT Profile

The profile(s) that are to be rendered in the image.

decoration

CONST_OBJECT View.GraphDecoration

A decorator that describes how the profiles(s) are to be rendered. The DrawSize (line width) and GraphColor (line color) properties are supported.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay.

Sample
image = Image.drawProfileInplace(image, profiles, decoration)
drawShape()
Short description

Render the position of one or several shapes into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The View.ShapeDecoration object is used to set graphical properties. The following parameters in the ShapeDecoration object are supported: - The LineColor property is used to set the border color of the rendered shape. - The FillColor property is used to set the fill color of the rendered shape. - The LineWidth property is used to set width of the border. Image world coordinate system handling: The shape coordinates are interpreted as world coordinates. That is, the coordinate system of the image is used to place the shapes properly. Missing data handling: This function does not use the missing data flag.

Keywords

display, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to render the shape(s) into. Supported image types are UINT8 and RGB.

shapes

CONST_OBJECT Shape

The shape(s) that are to be rendered in the image.

decoration

CONST_OBJECT View.ShapeDecoration

A decorator that describes how the shape(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay.

Sample
image = Image.drawShape(image, shapes, decoration)
drawShapeInplace()
Short description

Inplace version of the Image.drawShape function which modifies the input image. See base function for full documentation.

Keywords

display, overlay, paint, plot, print, render, rasterize

Parameters
Name Type Description

image

OBJECT Image

The image to render the shape(s) into. Supported image type is RGB.

shapes

CONST_OBJECT Shape

The shape(s) that are to be rendered in the image.

decoration

CONST_OBJECT View.ShapeDecoration

A decorator that describes how the shape(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description.

Return values
Name Type Description

image

OBJECT Image

RGB image with rendered overlay. Reference to input image.

Sample
image = Image.drawShapeInplace(image, shapes, decoration)
drawText()
Short description

Renders text into an image by modifying the pixel values. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. Not all features of the TextDecoration input are supported. Features that are supported are the following: * Position - Fully supported. * Color - Does not support opacity. * Size - Approximately matching to viewer settings. * Font family - SANSSERIF and SERIF are supported, MONOSPACE is unsupported. * Font weight - Fully supported, but does not exactly match viewer behavior. * Horizontal alignment - Full support apart from JUSTIFY, but does not exactly match viewer behavior. * Vertical alignment - Fully supported, but does not exactly match viewer behavior Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The font position will adjust to the image coordinate system, but the font size will only scale with the y-resolution. Missing data handling: This function does not use the missing data flag.

Keywords

characters, display, draw, letters, overlay, paint, plot, print, render, write, rasterize

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to render the text into. This image is overwritten with the rendered text. Supported image types are UINT8 and RGB.

text

STRING

The characters that cannot be rendered using the specified font are replaced by question marks.

decoration

CONST_OBJECT View.TextDecoration

A decorator that describes how the text should be rendered.

Return values
Name Type Description

result

OBJECT Image

RGB image with rendered overlay.

Sample
result = Image.drawText(image, text, decoration)
drawTextInplace()
Short description

Inplace version of the Image.drawText function that modifies the input image. See base function for full documentation.

Keywords

characters, display, draw, letters, overlay, paint, plot, print, render, write, rasterize

Parameters
Name Type Description

image

OBJECT Image

The image to render the text into. This image is overwritten with the rendered text. Supported image type is RGB.

text

STRING

The characters that cannot be rendered using the specified font are replaced by question marks.

decoration

CONST_OBJECT View.TextDecoration

A decorator that describes how the region(s) should be rendered.

Return values
Name Type Description

result

OBJECT Image

RGB image with rendered overlay. Reference to input image.

Sample
result = Image.drawTextInplace(image, text, decoration)
equalizeHistogram()
Short description

Applies histogram equalization to an image.

Keywords

contrast, intensity, normalize, stretch, scale

See also

Image.normalize

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Only uint8 type supported.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.

Return values
Name Type Description

equalizedImage

OBJECT Image

Equalized image

Sample
equalizedImage = Image.equalizeHistogram(image)
extractColumnProfile()
Short description

Extracts one profile from an image column. The number of samples in the profile is always the same as the number of pixels between the start and end row (end position is included). Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The image column to extract from is provided as a zero-based integer pixel coordinate. The coordinate representation in the generated Profile object will be of implicit 2D or 1D type. Default is 2D, where the start point is the (x,y) world coordinates of the first extracted pixel in the image column and the delta vector the spacing between pixels in the y-dimension. Optionally, 1D coordinates can be returned, in which case the sample coordinates are set to the y-coordinates of the sampled pixels. Missing data handling: Valid data flags are enabled in the output profile if and only if the image contains missing data. Points sampled on missing data pixels are marked as invalid.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image. All pixel types are supported.

column

INT

The column to extract as a profile.

startRow

INT

The first row index to extract. If no index is given 0 will be used.

stopRow

INT

The last row index extract. If no index is given the image height-1 will be used.

sampleCoordinates1D

BOOL

If set to true, the output profile will have implicit 1D coordinates, keeping only the y-coordinates of the sample points. Default is false, generating implicit 2D sample coordinates.

Return values
Name Type Description

profile

OBJECT Profile

Sampled profile, or nil if unsuccessful.

Sample
local profile = Image.extractColumnProfile(image, column, startRow, stopRow)
extractProfile()
Short description

Samples image values evenly along a contour defined by a 2D Shape object and generates a Profile object. Supported shape types are line segment, arc, circle and polyline. Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The coordinate representation in the generated Profile object will be of implicit type if the contour shape allows it. For example, coordinates along a line segment contour can be represented using the implicit start + delta vector representation. For more complex contours such as a circle, an explicit coordinate representation is used in the Profile object where all the sample points are stored as individual entries. If the contour shape is closed, e.g., a circle, the closed flag in the Profile is also set. Missing data handling: Valid data flags are enabled in the output profile if and only if the image has missing data activated. Points sampled on missing data are marked as invalid. Points sampled outside the image are marked as invalid. In the latter case and if the image does not have missing data activated, the valid flags of the generated profile are set accordingly but are not enabled.

Keywords

line segment, sample

Parameters
Name Type Description

image

CONST_OBJECT Image

The image. All pixel types are supported.

shape

CONST_OBJECT Shape

The shape to sample along. Supported shapes are line segment, arc, circle and polyline.

sampleCount

INT

The number of samples to take, evenly spaced along the input shape.

interpolation

ENUM InterpolationMethod

Interpolation method, NEAREST or LINEAR. Default is NEAREST.

Return values
Name Type Description

profile

OBJECT Profile

Generated Profile object, or nil if unsuccessful.

Sample
local profile = Image.extractProfile(image, shape, sampleCount, interpolation)
extractRowProfile()
Short description

Extracts one profile from an image row. The number of samples in the profile is always the same as the number of pixels between the start and end column (end position is included). Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The image row to extract from is provided as a zero-based integer pixel coordinate. The coordinate representation in the generated Profile object will be of implicit 2D or 1D type. Default is 2D, where the start point is the (x,y) world coordinates of the first extracted pixel in the image row and the delta vector the spacing between pixels in the x-dimension. Optionally, 1D coordinates can be returned, in which case the sample coordinates are set to the x-coordinates of the sampled pixels. Missing data handling: Valid data flags are enabled in the output profile if and only if the image contains missing data. Points sampled on missing data pixels are marked as invalid.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image. All pixel types are supported.

row

INT

The row to extract as a profile, zero-based.

startColumn

INT

The first column index to extract, zero-based. If no index is given 0 will be used.

stopColumn

INT

The last column index extract, zero-based. If no index is given the image width-1 will be used.

sampleCoordinates1D

BOOL

If set to true, the output profile will have implicit 1D coordinates, keeping only the x-coordinates of the sample points. Default is false, generating implicit 2D sample coordinates.

Return values
Name Type Description

profile

OBJECT Profile

Sampled profile, or nil if unsuccessful.

Sample
local profile = Image.extractRowProfile(image, row, startColumn, stopColumn, sampleCoordinates1D)
fillRegion()
Short description

Set all pixels within the given region(s) in the target image to a specific value in world coordinates. The pixels outside the input region keep their original values. A new image with updated values is returned, and the input image is left unchanged. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. If the value parameter is outside the image value range it will be clamped to the closest valid value. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is kept in the output image, but the pixels in the fill region will be updated with non missing data.

Keywords

inpaint, flood

Parameters
Name Type Description

inputImage

CONST_OBJECT Image

Input image.

region

CONST_OBJECT Image.PixelRegion

The region(s) to fill.

value

FLOAT

World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image.

Return values
Name Type Description

outputImage

OBJECT Image

Result image or nil if operation failed.

Sample
outputImage = Image.fillRegion(inputImage, region, value)
fillRegionInplace()
Short description

Inplace version of the Image.fillRegion function that modifies the input image. See base function for full documentation.

Keywords

inpaint, flood

Parameters
Name Type Description

image

OBJECT Image

The image. This image is overwritten with the result image.

region

CONST_OBJECT Image.PixelRegion

The region(s) to fill.

value

FLOAT

World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.fillRegionInplace(image, region, value)
findLineSegments()
Short description

Finds line segments in an image. Returns a list of 2D line segments represented as a Shape type. An empty list is returned when no line segments were found during an otherwise successful call. This function is currently limited to uint8 pixel type images. Image world coordinate system handling: The output Shape line segments are expressed using the image world coordinate system in the xy-dimensions. The z-dimension is not used in this function. Missing data handling: This function does not support images with missing data. Fill in missing data before hand, using e.g., missingDataSetAll.

Keywords

edge, hough

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Support currently limited to uint8 pixel type.

scale

FLOAT

The scale of the image that will be used to find the lines. Accepted values are strictly larger than zero and smaller or equal to one. Optional, default is 0.8.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.

mergeLines

BOOL

Optional flag to merge line segments that are on the same line. Defaults to false.

Return values
Name Type Description

lineSegments

OBJECT Shape

The detected line segments in image world coordinates, or nil on failure.

Sample
lineSegments = Image.findLineSegments(image)
findLocalExtrema()
Short description

Finds local extreme points (minima or maxima) in an image. A point is a local maxima if it is larger than all points within a neighborhood of the specified size. An optional contrast threshold level can be defined that sets a required value difference between the local maxima and the smallest value in the neighborhood. For local plateaus, where several pixels have the same value, the top left pixel is reported. An absolute threshold can be specified, if so, point values must exceed the threshold value to be reported. Local minima are detected similarly. Early stopping is used, the neighborhood is only searched until it is clear that the pixel at hand is not an extremal point, starting with the four closest neighbor pixels. The function thus runs faster on smooth images. The absoluteThreshold can also be used to speed up the processing, only considering pixels larger (smaller) than the threshold. The entire neighborhood must fit within the image around extreme points e.g. if neighborhoodSize = 5, no extreme points will be detected closer than three pixels from the image border. Image world coordinate system handling: The thresholds are specified in world values, taking z-origin and pixel size into account. The output pixel region is defined on the pixel grid of the image. Missing data handling: This function does not handle missing data. Remove missing data before calling this function.

Keywords

maxima, min, minima, max

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, uint32, int8, int16, float32 and float64.

extremaType

ENUM ExtremaType

Which type of extrema to look for. MIN or MAX.

neighborhoodSize

INT

The neighborhood size, width and height in pixels. Must be odd and >= 3. Default is 3.

contrastThreshold

FLOAT

Required height of the peak/valley (world coordinate value difference between the extreme point and surrounding points). Set to zero to disable (default).

contrastDifferenceMode

ENUM ContrastDifferenceMode

Determines how the difference between the extreme point and the surrounding points is calculated. Default is ONE, at least one point in the neighborhood should differ more than contrastThreshold from the local extremal point.

absoluteThreshold

FLOAT

Absolute threshold, extremal points must be above (maxima) or below (minima) this value to be included in the output. By default, this threshold is not used.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.

Return values
Name Type Description

extremalRegions

OBJECT Image.PixelRegion

PixelRegion with local extremal points.

Sample
extremalRegions = Image.findLocalExtrema(image, extremaType, neighborhoodSize, contrastThreshold, contrastDifferenceMode, absoluteThreshold, region)
gauss()
Short description

Applies a Gaussian filter to smooth an image. Image world coordinate system handling: The Gaussian filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.

Keywords

blur, convolve, denoise, filter, smooth

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, int16, float32 and float64.

kernelSizePix

INT

Size of the kernel, must be positive and odd.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined.

fillMissingData

BOOL

Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false.

gaussianFilterType

ENUM GaussianFilterType

Optional selection of which algorithm to use for Gaussian smoothing. Default is dependent on the filter size, a Gaussian kernel is used for small filters and an IIR approximation is used for large filters.

Return values
Name Type Description

smoothImage

OBJECT Image

Output image smoothed by the Gaussian filter. Same type as input image.

Sample
smoothImage = Image.gauss(image, kernelSizePix)
getFlatRegion()
Short description

Find approximately flat regions in an image, typically a heightmap or distance image. The algorithm fits a plane to a local neighborhood around each pixel. If all pixel values / z-values in the neighborhood deviate less than a user-specified threshold from the fitted plane, the central pixel is considered to be in a flat region. There is a fast and slow method for the plane fitting, where the slower method uses all pixels in the neighborhood to estimate the plane and the fast method only uses the border values in the neighborhood. Smoothing the input image first using a blur, gauss or median filter can sometimes be advisable. Image world coordinate system handling: Every position in the output region will have a maximum distance to the fitted plane in world units evaluated on the all pixels under the kernel that is lower than the threshold supplied. Missing data handling: Missing data is accepted, but partly ignored. No pixels that are missing in the input will be part of the output region. For pixels neighboring missing data the missing data positions are allowed to influence the flatness evaluation, possibly breaking the flatness constraint.

Keywords

planar, planarity, roughness, structure, surface

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image.

threshold

FLOAT

Distance tolerance from the locally fitted plane in world units, e.g., millimeters. If all pixels in the neighborhood deviate less than the threshold the central pixel is classified as flat. The Image.getFlatness function can give an indication of possible threshold values.

neighborhoodSize

INT

The size of the neighborhood in pixels. Must be positive and odd. Default value is 13 pixels.

fast

BOOL

Faster central difference estimate (true) or slower least squares fit (false) for the plane fitting. Default is true.

pixelRegion

CONST_OBJECT Image.PixelRegion

Optional pixelregion specifying where in the image to perform the operation.

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

The resulting region of flat pixels.

Sample
outputRegion = Image.getFlatRegion(image, threshold, neighborhoodSize)
getFlatness()
Short description

Calculates a flatness measure for each pixel in an image. A pixel with a value close to zero means approximate coplanarity with its neighbors. The algorithm fits a plane to a local neighborhood around each pixel and gives out the maximum deviation from the plane over all pixels in the neighborhood. There is a fast and slow method for the plane fitting, where the slower method uses all pixels in the neighborhood to estimate the plane and the fast method only uses the border values in the neighborhood. Smoothing the input image first using a blur, gauss or median filter can sometimes be advisable. Image world coordinate system handling: Every pixel in the flatness image stores the maximum distance to the fitted plane in world units evaluated on the all pixels under the neighborhood. Missing data handling: Missing data is accepted, but partly ignored. All pixels that are missing data in the input image will get a negative planarity measure (corresponding to 1 z-pixelsize ). For pixels neighboring missing data the missing data positions are allowed to influence the flatness evaluation, possibly inflating the flatness measure.

Keywords

planar, planarity, roughness, structure, surface

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image.

neighborhoodSize

INT

The size of the neighborhood in pixels. Must be positive and odd. Default value is 13 pixels.

fast

BOOL

Faster central difference estimate (true) or slower least squares fit (false). Default is true.

pixelRegion

CONST_OBJECT Image.PixelRegion

Optional pixelregion specifying where in the image to perform the operation.

Return values
Name Type Description

flatness

OBJECT Image

A FLOAT32 image with flatness estimates.

Sample
flatness = Image.getFlatness(image, neighborhoodSize)
getHeight()
Short description

Returns the height of an image.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to get the height of.

Return values
Name Type Description

height

INT

Height of the image in pixels.

Sample
local height = Image.getHeight(image)
getHistogram()
Short description

Get a histogram of the image values. If the image supports missing data, pixels marked as missing are not included in the histogram. The histogram is computed using world coordinates (z-axis offset and scaling have influence). If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. Pixels with values outside the interval are not counted. See also Image.PixelRegion.getHistogram.

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image, specifying values to use in the histogram.

binCount

INT

Number of bins. Uses 32 bins as default.

minValue

FLOAT

Minimum of the value range to cover. Uses an automatic range if omitted.

maxValue

FLOAT

Maximum of the value range to cover. Uses an automatic range if omitted.

Return values
Name Type Description

histogram

FLOAT

Histogram, represented as a vector of floats.

binCenters

FLOAT

The center of each histogram bin in the input value range.

Sample
histogram, centers = Image.getHistogram(image, 64)
getMax()
Short description

Returns the maximum pixel value in an image. The position of the first maximal value pixel and its uniqueness is also returned. Optionally, a pixel region may be provided. Image world coordinate system handling: The output value is specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are ignored.

Keywords

rank, statistics, maximum

Parameters
Name Type Description

image

CONST_OBJECT Image

The image.

region

CONST_OBJECT Image.PixelRegion

Optional region in which to find the min and max, default is the entire image.

Return values
Name Type Description

maxValue

FLOAT

The maximum pixel value in world coordinates (millimeters).

position

OBJECT Point

The position of the first maximal value pixel in the image scan order, in world coordinates (millimeters).

unique

BOOL

Boolean indicating if there is only one pixel with the maximal value.

Sample
maxValue = Image.getMax(image)
getMean()
Short description

Get the mean pixel value. If a region is provided, the mean is calculated within that region. By default, a reference plane z=0 is used. Another reference plane may be provided, giving the mean difference from that plane. Several regions in a list may be used, in which case one mean value is calculated for each region. When using multiple regions, empty regions are reported as having mean value zero. Image world coordinate system handling: The output mean value is specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are not included.

Keywords

average, statistics, mean

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image, defines the image from which to get pixel value input.

region

CONST_OBJECT Image.PixelRegion

Input region or regions, defines the region of image in which to calculate the mean, default is the entire image. If several regions are provided, a list of mean values is returned.

referenceSurface

CONST_OBJECT Shape3D

Reference plane, defines the zero level in world coordinates. Default is the plane z=0.

Return values
Name Type Description

mean

FLOAT

Mean value or list of mean values. Nil on error

Sample
mean = Image.getMean(image, region, referenceSurface)
getMedian()
Short description

Get the median value of the pixels within the region, a special case of Image.PixelRegion.getPercentiles. The median is derived from a histogram and it is approximate. Optionally, a reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0.

Keywords

percentile, statistics

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image, defines the image from which to get pixel value input.

region

CONST_OBJECT Image.PixelRegion

Input region or regions, defines the region of image in which to calculate the median, default is the entire image. If several regions are provided, a list of median values is returned.

referenceSurface

CONST_OBJECT Shape3D

Zero-reference plane for pixel world coordinate values. Optional, default is the plane z=0.

Return values
Name Type Description

median

FLOAT

The approximate median(s).

Sample
median = Image.getMedian(image, region, referenceSurface)
getMin()
Short description

Returns the minimum pixel value in an image. The position of the first minimal value pixel and its uniqueness is also returned. Optionally, a pixel region may be provided. Image world coordinate system handling: The output value is specified in image world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are ignored.

Keywords

rank, statistics, minimum

Parameters
Name Type Description

image

CONST_OBJECT Image

The image.

region

CONST_OBJECT Image.PixelRegion

Optional region in which to find the min and max, default is the entire image.

Return values
Name Type Description

minValue

FLOAT

The minimum pixel value in world coordinates (millimeters).

position

OBJECT Point

The position of the first minimal value pixel in the image scan order, in world coordinates (millimeters).

unique

BOOL

Boolean indicating if there is only one pixel with the minimal value.

Sample
minValue = Image.getMin(image)
getMinMax()
Short description

Returns the minimum and maximum pixel value in an image. Optionally, a pixel region may be provided. Image world coordinate system handling: The output min and max values are specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are ignored.

Keywords

maximum, rank, statistics, minimum

Parameters
Name Type Description

image

CONST_OBJECT Image

The image.

region

CONST_OBJECT Image.PixelRegion

Optional region in which to find the min and max, default is the entire image.

Return values
Name Type Description

minValue

FLOAT

The minimum pixel value in world coordinates (millimeters).

maxValue

FLOAT

The maximum pixel value in world coordinates (millimeters).

minPosition

OBJECT Point

The position of the first minimal value pixel in the image scan order, in world coordinates (millimeters).

maxPosition

OBJECT Point

The position of the first maximal value pixel in the image scan order, in world coordinates (millimeters).

minUnique

BOOL

Boolean indicating if there is only one pixel with the minimal value.

maxUnique

BOOL

Boolean indicating if there is only one pixel with the maximal value.

Sample
minValue, maxValue, minPosition, maxPosition, minUnique, maxUnique = Image.getMinMax(image)
getMissingDataFlag()
Short description

Gets the missing data setting in the image. 0 means no missing data handling, 1 means that the value 0 is treated as missing data.

Parameters
Name Type Description

image

CONST_OBJECT Image

Return values
Name Type Description

missingDataFlag

INT

Returns the missing data setting.

Sample
local missingDataFlag = Image.getMissingDataFlag(image)
getMissingDataImage()
Short description

Creates a binary image indicating the missing data pixels in the source image. Image world coordinate system handling: The output binary image gets the same x,y-origin and x,y-pixelsize as the input image, but the z-origin is set to 0 and the z-pixelsize to 1. Missing data handling: The output image has no missing data flag set as it is a binary image.

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

missingValue

INT

The value to assign result pixels for missing data in the source image. Default = 1

dataValue

INT

The value to assign result pixels for data in the source image. Default = 0

Return values
Name Type Description

result

OBJECT Image

The resulting binary image, always of uint8 pixel type

Sample
result = Image.getMissingDataImage(image)
getMissingDataRegion()
Short description

Creates a PixelRegion object of all missing data pixels in the source image.

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

The region containing all missing data pixels.

Sample
region = Image.getMissingDataRegion(image)
getOrigin()
Short description

Retrieves the origin of the image world coordinate in the image. The origin corresponds to the world coordinate of the top-left image pixel.

See also

Image.setOrigin

Parameters
Name Type Description

image

CONST_OBJECT Image

Return values
Name Type Description

origin

OBJECT Point

Returns the origin as a point in 3D.

Sample
local origin = Image.getOrigin(image)
getPercentiles()
Short description

Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. All values are derived from a histogram and are approximate. Optionally, a reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0.

Keywords

statistics

See also

Image.getMedian

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image, defines the image from which to get pixel value input.

percentileLevels

FLOAT

Percentile levels in the range (0..1)

region

CONST_OBJECT Image.PixelRegion

Input region, default is the entire image.

referenceSurface

CONST_OBJECT Shape3D

Zero-reference plane for pixel world coordinate values. Optional, default is the plane z=0.

Return values
Name Type Description

values

FLOAT

Output values

Sample
values = Image.getPercentiles(image, percentileLevels, region, referenceSurface)
getPixel()
Short description

Returns the raw pixel value of an image at position (x,y) in pixel coordinates. For monochrome image types this is a single float value, for RGB24 a vector of three float values in the order red, green, blue.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to get the pixel from.

x

INT

The x pixel coordinate.

y

INT

The y pixel coordinate.

Return values
Name Type Description

value

FLOAT

The raw pixel value, or a vector of RGB values, or nil for invalid coordinates.

Sample
local value = Image.getPixel(image, 5, 6)
getPixelSize()
Short description

Retrieves the pixel size of the image world coordinate system.

Parameters
Name Type Description

image

CONST_OBJECT Image

Return values
Name Type Description

sizeX

FLOAT

Returns the size of a pixel in the X dimension in world coordinate units.

sizeY

FLOAT

Returns the size of a pixel in the Y dimension in world coordinate units.

sizeZ

FLOAT

Returns the size of a pixel in the Z dimension in world coordinate units.

Sample
local sizeX, sizeY, sizeZ = Image.getPixelSize(image)
getSize()
Short description

Returns the width and height of an image.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to get the size of.

Return values
Name Type Description

width

INT

Width of the image in pixels.

height

INT

Height of the image in pixels.

Sample
local width, height = Image.getSize(image)
getSum()
Short description

Returns the sum of the pixel values in an image. Image world coordinate system handling: The sum is in world coordinates, i.e., the origin and pixel size in the z-dimension are considered should the image represent a height map, distance or range image. Missing data handling: This operation does not support missing data images, fill in missing data before calling this function.

Keywords

statistics

See also

Image.getMean

Parameters
Name Type Description

image

CONST_OBJECT Image

The image.

Return values
Name Type Description

imageSum

FLOAT

The sum of all pixels expressed in world coordinates (millimeters)

Sample
imageSum = Image.getSum(image)
getType()
Short description

Returns the pixel type of the image.

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image.

Return values
Name Type Description

pixelType

ENUM ImageType

The pixel type (e.g.: uint8, int16, float64).

Sample
local pixelType = Image.getType(image)
getValidDataRegion()
Short description

Creates a PixelRegion object of all non-missing data pixels in the source image.

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

A PixelRegion containing all valid data pixels.

Sample
local region = Image.getValidDataRegion(image)
getWidth()
Short description

Returns the width of an image.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to get the width of.

Return values
Name Type Description

width

INT

Width of the image in pixels.

Sample
local width = Image.getWidth(image)
getWorldZ()
Short description

Returns the z-values at given 2D (x,y)-points, interpreting the image as a range image. Linear interpolation is used for positions between the pixel grid positions. For points outside the image the z-origin value is return corresponding to raw pixel value 0. Coordinate system handling: The image world coordinate system is used in this operation, i.e., the input 2D points are interpreted using the pixelsizes and origin in the (x,y)-dimensions and the output z value is also in world coordinates. Missing data handling: Missing data is respected so that missing data pixels are ignored in the interpolation calculation.

Keywords

getHeight

See also

Image.toWorldZ

Parameters
Name Type Description

image

CONST_OBJECT Image

The image.

points

CONST_OBJECT Point

The 2D point to sample at, or a list of 2D points, in world coordinates.

Return values
Name Type Description

valuesZ

FLOAT

Z value or values in world coordinates, or nil if unsuccessful.

Sample
local valuesZ = Image.getWorldZ(image, points)
growRegion()
Short description

Starting from the seed regions, the regions are expanded to fill the pixel areas whose world pixel values in the image lies between the lower and upper threshold in world coordinates. Pixels with missing data are not grown into. Pixels included in the seed region will always be included in the output region, independent of the corresponding pixel value and missing status. Image world coordinate system handling: The thresholds are interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 or a z-pixelsize different than 1. Missing data handling: Pixels with missing data are not included in the grown region, unless covered by the seed region.

Keywords

seeded, segmentation, floodfill

Parameters
Name Type Description

image

CONST_OBJECT Image

The image indicating where the region should grow.

seedRegion

CONST_OBJECT Image.PixelRegion

The region to grow.

minThreshold

FLOAT

Minimum value to allow growth. Optional, default is the smallest representable value.

maxThreshold

FLOAT

Maximum value to allow growth. Optional, default is the largest representable value.

Return values
Name Type Description

grownRegion

OBJECT Image.PixelRegion

Result region or nil if operation failed.

Sample
grownRegion = Image.growRegion(image, seedRegion, minThreshold, maxThreshold)
houghTransformCircle()
Short description

Finds circle candidates with a given radius in an edge image where any non-zero pixel is considered an edge. The output is an accumulator image binned over circle centers in world coordinates. The world coordinates of the output accumulator directly matches circle centers, i.e. the world coordinates of a maxima in the accumulator image corresponds directly to the input image circle center in world coordinates. Use Image.houghTransformExtremaToCircles to create circles from accumulator image maxima (as a pixel region), or extract maxima as points and use Shape.createCircle(points, radius) directly. Image world coordinate system handling: Input image world coordinates are used. The radius is in world coordinates. The accumulator world coordinates directly relate maxima to circle centers. Pixel values in the input image are interpreted in raw pixel values. Missing data handling: Missing data are interpreted as not edges.

Parameters
Name Type Description

edgeImage

CONST_OBJECT Image

Input image. Supported image types are uint8 and uint16. Non-zero pixels are counted as edges.

radius

FLOAT

The radius of circles to search for, in world coordinates.

resolutionX

INT

The number of bins to use for the x-position of the circles, also the width of the output image, default 200.

resolutionY

INT

The number of bins to use for the y-position of the circles, also the height of the output image, default 200.

Return values
Name Type Description

houghAccumulator

OBJECT Image

Circle candidate center accumulator image.

Sample
houghAccumulator = Image.houghTransformCircle(edgeImage, radius, resolutionX, resolutionY)
houghTransformExtremaToCircles()
Short description

Converts pixels extracted from an accumulator image obtained from houghTransformCircle to geometrical circles. The accumulator image is required to get the world coordinate system and accumulator values. Results are sorted in descending order by accumulator value. Image world coordinate system handling: Pixel region of extremas should be related to the accumulator image. Circles are returned in world coordinates. Missing data handling: Not applicable, there is no missing data in the input accumulator image.

Parameters
Name Type Description

accumulatorImage

CONST_OBJECT Image

Accumulator image as returned from houghTransformCircle.

extremalRegion

CONST_OBJECT Image.PixelRegion

Pixel region with extremal points extracted from the accumulator image, will be recalculated to the corresponding circles.

radius

FLOAT

Radius of the circles to create.

Return values
Name Type Description

circles

OBJECT Shape

Circles as shapes, or nil on error.

accumulatorValues

FLOAT

Accumulator image value corresponding to each circle.

Sample
circles, accumulatorValues = Image.houghTransformExtremaToCircles(accumulatorImage, extremalRegion, radius
houghTransformExtremaToLines()
Short description

Converts pixels extracted from an accumulator image obtained from houghTransformLine to geometrical lines. Both the accumulator and edge images are required to get the world coordinate system. Since horizontal lines end up just where the accumulator image wraps around, the accumulator is usually extended with a few extra rows. These may result in duplicate line detections (the direction differ by pi, with opposite sign of the distance to the image center). By default, such duplicate lines are removed but this feature can be turned off. The accumulator value corresponding to each line candidate is returned. Results are sorted in descending order by accumulator value. Image world coordinate system handling: Pixel region of extremas should be related to the accumulator image. Lines are returned in world coordinates of the original input image. Missing data handling: Not applicable, there is no missing data in the input accumulator image.

Parameters
Name Type Description

accumulatorImage

CONST_OBJECT Image

Accumulator image as returned from houghTransformLines.

extremalRegion

CONST_OBJECT Image.PixelRegion

Pixel region with extremal points extracted from the accumulator image, will be recalculated to the corresponding lines.

edgeImage

CONST_OBJECT Image

Input image as sent to houghTransformLine, used for coordinate reference.

removeDuplicates

BOOL

Flag indicating if duplicate lines should be removed, default is true.

Return values
Name Type Description

lines

OBJECT Shape

Lines as shapes, or nil on error.

accumulatorValues

FLOAT

Accumulator image value corresponding to each line.

Sample
lines = Image.houghTransformExtremaToLines(accumulatorImage, extremalRegion, edgeImage, removeDuplicates)
houghTransformLine()
Short description

Finds line candidates in an edge image where any non-zero pixel is considered an edge. The output is an accumulator image binned over line candidate direction and signed distance from the center of the input image. E.g. a line candidate with direction pi/2 and distance -5 is a vertical line located five world coordinate units to the left of the center point of the input image. Line candidates are on the form x*sin(theta) + y*cos(theta) = d, where x and y are input image positions relative to the center of the input image, d is the signed distance from the center of the input image and theta is the line direction. All are expressed in world coordinates. d is binned over distanceBins bins which also is the width of the output image. Theta is binned over directionBins bins. The range of theta is from zero to pi, d is from minus to plus half the diagonal of the input image. Since the direction parameter is circular in nature, a maxima at the upper and lower accumulator image border (theta is zero or pi) with opposite signs of d correspond to the same line. Since maxima extraction routines tend to skip maxima close to image borders, a few extra rows are added to the bottom of the accumulator image, corresponding to the first rows of accumulators. The number of extra rows is set by the overlapBins parameters, recommended to be set to the maxima extraction filter size. The accumulator image height is thus directionBins + overlapBins. Use houghTransformExtremaToLines to transform extrema from the accumulator image into Shape lines. Image world coordinate system handling: Input image world coordinates are used. All output values are with respect to the center of the input image. The output image world coordinates are set to directly get d and theta values. Raw pixel values of the input image are used. Missing data handling: Missing data are interpreted as not edges.

Parameters
Name Type Description

edgeImage

CONST_OBJECT Image

Input image. Supported image types are uint8 and uint16. Non-zero pixels are counted as edges.

distanceBins

INT

The number of bins to use for the distance to the line from the edge image center, the width of the output image, default 200.

directionBins

INT

The number of bins to use for the direction of the line, the height of the output image, default 360.

overlapBins

INT

The number of extra rows to add at the bottom of the accumulator image, overlapping with the first rows. Recommended value is the size of the maxima filter to be used, default is 5.

Return values
Name Type Description

houghAccumulator

OBJECT Image

Line candidate accumulator image.

Sample
houghAccumulator = Image.houghTransformLine(edgeImage, distanceBins, directionBins, overlapBins)
inpaint()
Short description

Replaces the image content in a specified region with the content around the region. This is done in an iterative manner and increasing the radius increases the speed of the algorithm, at the cost of quality of the result. Image world coordinate system handling: The world coordinate system of the input image is not used. The output will have the same coordinate system as the input image. Missing data handling: Operation is performed in raw pixel values. If there are missing data along the borders of the region it will be used for inpainting.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image in which to perform inpainting.

region

CONST_OBJECT Image.PixelRegion

The region to be replaced.

radius

FLOAT

Pixel radius used by inpainting algorithm. Default is 3.0.

method

ENUM InpaintMethod

Inpainting method. Default is NAVIER_STOKES.

Return values
Name Type Description

result

OBJECT Image

The resulting image.

Sample
local result = Image.inpaint(image, region)
invert()
Short description

Inverts the pixel values in the image, so that dark becomes bright and vice versa. The operation imOutput = getMax(imInput) - imInput. The function only accepts unsigned integer pixel types, to invert signed pixel type use a negation instead. To do an inversion in the sense 1/x use the pow-function. Image world coordinate system handling: The output image keeps the coordinate system of the input image. Missing data handling: A missing data pixel in the input image results in a missing data pixel in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

brightness, contrast, inverse

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

Return values
Name Type Description

result

OBJECT Image

The inverted image.

Sample
result = Image.invert(image)
invertInplace()
Short description

Inplace version of the Image.invert function that modifies the input image. See base function for full documentation.

Keywords

brightness, contrast, inverse

See also

Image.invert

Parameters
Name Type Description

image

OBJECT Image

The source image. This image is overwritten with the result image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.invertInplace(image)
isEqual()
Short description

Checks if two images are equal, both in terms of size, type and pixel content. This function disregards the missing data flag and image world coordinate information and looks only at raw pixel values.

Keywords

compare, similar, check

Parameters
Name Type Description

image1

CONST_OBJECT Image

The first source image.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

BOOL

True if the images have identical size and pixel type, and equal contents at each pixel.

Sample
result = Image.isEqual(image1, image2)
isWithinBounds()
Short description

Checks whether a pixel coordinate is within the bounds of the image.

Parameters
Name Type Description

image

CONST_OBJECT Image

x

INT

The x pixel coordinate of the point to be checked.

y

INT

The y pixel coordinate of the point to be checked.

Return values
Name Type Description

isInBounds

BOOL

Returns true if the point is within the image, false otherwise.

Sample
local isInBounds = Image.isWithinBounds(image, 15, 15)
laplace()
Short description

Applies a Laplace filter to the input image, i.e., the sum of the local second-order gradients in the x- and y-directions. Image world coordinate system handling: The Laplace filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.

Keywords

convolve, derivative, gradient, edge

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, float32 and float64.

kernelSizePix

INT

Size of the kernel, must be positive, odd and not larger than 29.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Pixel values outside the region are undefined.

Return values
Name Type Description

laplaceImage

OBJECT Image

Output image with the Laplace values.

Sample
laplaceImage = Image.laplace(image, kernelSizePix)
load()
Short description

Loads an image from the specified file path. The format is defined by the file extension: .bmp: Bitmap .png: PNG .jpg: JPEG (not supported by all devices) .json: JSON .msgpack: MessagePack

See also

File, Object.load

Parameters
Name Type Description

filepath

STRING

The path and name of the file to load the image from.

Return values
Name Type Description

image

OBJECT Image

The Image object which is loaded.

Sample
local image = Image.load("resources/image.bmp")
max()
Short description

Creates an image with the maximum pixel values of the source images. The images must be of equal size and pixel type. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.

Keywords

arithmetic, compare, maximum

Parameters
Name Type Description

image1

CONST_OBJECT Image

The first source image.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

The maximum image.

Sample
result = Image.max(image1, image2)
maxInplace()
Short description

Inplace version of the Image.max function which modifies the first input image to contain the pixelwise maximum of the input images. See base function for full documentation.

Keywords

arithmetic, compare, maximum

Parameters
Name Type Description

image1

OBJECT Image

The first source image. This image is overwritten with the pixelwise maximum.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.maxInplace(image1, image2)
median()
Short description

Applies median filter to the image to smooth and remove noise. Image world coordinate system handling: The median filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.

Keywords

denoise, edge preserving, filter, smooth

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, int16 and float32.

kernelSizePix

INT

Size of the kernel, must be positive and odd. For kernel sizes larger than 5 the only supported image type is uint8.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined.

fillMissingData

BOOL

Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false.

Return values
Name Type Description

medianImage

OBJECT Image

Output image blurred by the median filter.

Sample
medianImage = Image.median(image, kernelSizePix)
min()
Short description

Creates an image with the minimum pixel values of the source images. The images must be of equal size and pixel type. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.

Keywords

arithmetic, compare, minimum

Parameters
Name Type Description

image1

CONST_OBJECT Image

The first source image.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

The minimum image.

Sample
result = Image.min(image1, image2)
minInplace()
Short description

Inplace version of the Image.min function which modifies the first input image to contain the pixelwise minimum of the input images. See base function for full documentation.

Keywords

arithmetic, compare, minimum

Parameters
Name Type Description

image1

OBJECT Image

The first source image. This image is overwritten with the pixelwise minimum.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.minInplace(image1, image2)
mirror()
Short description

Mirrors an image in the horizontal or vertical axis. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is mirrored. Missing data handling: All missing data values will be retained after mirroring.

Keywords

flip

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image.

mirrorHorizontally

BOOL

Set to true to mirror horizontally in the vertical axis, set to false to mirror vertically in the horizontal axis.

Return values
Name Type Description

mirroredImage

OBJECT Image

The mirrored image

Sample
mirroredImage = Image.mirror(image, mirrorHorizontally)
missingDataReduce()
Short description

Reduces missing data pixels in an image by using valid values in the neighborhood. Valid pixel values are unaffected. This will fill in scattered missing data values but larger patches of missing data will remain. The type of operation performed to fill a missing pixel is selected using the method parameter. Optionally, reduction of missing data can be limited to a region in the image. Valid pixel values within a neighborhood but outside the region will still be used to fill missing data. To fill a missing pixel, at least one quarter of the neighbor pixels need to have valid values. The available methods are: MAX - Sets missing pixels to the maximum valid value in the neighborhood. MIN - Sets missing pixels to the minimum valid value in the neighborhood. MEAN - Sets missing pixels to the mean of all valid values in the neighborhood. MEDIAN - Sets missing pixels to the median of all valid values in the neighborhood. EDGE - Fills missing values by edge-preserving interpolation among pixels in the 3x3 pixel neighborhood. A missing data pixel will be filled in only if there are valid values on both sides of a pixel. For all methods except EDGE, the neighborhood is nSize-by-nSize pixels. nSize must be odd and at least three. For method EDGE, nSize determines how many times the algorithm will be repeated. For EDGE, nSize must be a positive integer.

Parameters
Name Type Description

inputImage

CONST_OBJECT Image

The input image. An error is returned if the input image does not have the missing data flag set.

method

ENUM MissingDataMethod

Method to be used for reducing missing data.

nSize

INT

The size of the neighborhood for most methods, the number of iterations for EDGE. Default is 3.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the filter operation is only performed within this region. This can save a lot of computation time, if the region is small.

Return values
Name Type Description

outputImage

OBJECT Image

The output image, or nil if an error occurred.

Sample
outputImage = Image.missingDataReduce(inputImage, method, nSize, region)
missingDataSetAll()
Short description

Sets all missing data pixels in the entire image or within a specified region to a given value. All missing pixels are set and the missing data flag of the image is cleared. If a region is provided, only pixels within the region are considered. The missing data flag of the image is still cleared, leaving any pixels with missing data outside the region in an undetermined state. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is removed from the output image, also if the operation is only performed within a region of interest.

Parameters
Name Type Description

image

CONST_OBJECT Image

The input image.

valueWorld

FLOAT

The value to set, in world coordinates considering z-origin and z-pixelsize if applicable.

region

CONST_OBJECT Image.PixelRegion

A region of interest to operate within. Optional, default is operate on the entire image.

Return values
Name Type Description

result

OBJECT Image

The output image.

Sample
result = Image.missingDataSetAll(image, value, region)
missingDataSetAllInplace()
Short description

Inplace version of the Image.missingDataSetAll function that modifies the input image. See base function for full documentation.

Parameters
Name Type Description

image

OBJECT Image

The image to set missing data in. This image is overwritten with the result image.

valueWorld

FLOAT

The value to set, in world coordinates considering z-origin and z-pixelsize if applicable.

region

CONST_OBJECT Image.PixelRegion

A region of interest to operate within. Optional, default is operate on the entire image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.missingDataSetAllInplace(image, value, region)
missingDataSetSurface()
Short description

Sets all missing data pixels to the surface value, values are clamped to the representable range of the image. All valid values are left unchanged. If a region not covering the full image is used, any missing data outside the region will be left in an undetermined state. Currently, only a plane surface represented as a Shape3D is supported, other surface types may be supported in the future. Image world coordinate system handling: The surface is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: This function replaces all missing data pixels with the surface value. The missing data flag for the output image is removed, also when this operation is performed only within a specified region of interest.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to set missing data in.

surface

CONST_OBJECT Shape3D

The surface to clamp to, represented as a Shape3D. Currently only a plane type is supported, in future more surface types may be supported.

region

CONST_OBJECT Image.PixelRegion

Optional region where the operation is to be performed, default is the full image.

Return values
Name Type Description

clampedImage

OBJECT Image

The image without missing data. Nil if an error occurred.

Sample
clampedImage = Image.missingDataSetSurface(image, surface, region)
missingDataSetSurfaceInplace()
Short description

Inplace version of the Image.missingDataSetSurface function which modifies the input image by adding the value of a given plane. See base function for full documentation.

Parameters
Name Type Description

image

OBJECT Image

The image to set missing data in. This image is overwritten and the missing data is set according to the surface value.

surface

CONST_OBJECT Shape3D

The surface to clamp to, represented as a Shape3D. Currently only a plane type is supported, in future more surface types may be supported.

region

CONST_OBJECT Image.PixelRegion

Optional region where the operation is to be performed, default is the full image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.missingDataSetSurfaceInplace(image, surface, region)
morphology()
Short description

A morphological transformation applied to grayscale images. The possible transformation types are: ERODE, DILATE, OPEN, CLOSE, GRADIENT, TOPHAT and BLACKHAT. A circular structuring element/kernel is used for all types. The diameter of the kernel can be specified by diameterPix. For erosion the basic idea is just like soil erosion, it erodes away the boundaries of an object making it thinner. The dilation is the opposite transformation. The elements of the kernel contain: 0-background or 1-foreground. It is centered at each image pixel and defines the neighborhood pixels to be used. For grayscale erosion the new pixel value corresponds to the minimum value of the image pixels under the structuring element foreground. Similarly, for grayscale dilation the maximum of the neighborhood is used. The remaining transformations are: opening - erosion followed by dilation; closing - dilation followed by erosion; morphological gradient - difference between dilation and erosion; top hat - difference between input image and opening; black hat - difference between closing and input image. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The diameter of the structuring element is in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.

Keywords

binary, blackhat, close, erode, open, tophat, dilate

Parameters
Name Type Description

imageIn

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, int8, int16, int32, float32 and float64.

diameterPix

INT

The diameter of the circular structuring element/kernel in pixels. The value must be odd and between 3 and 51.

transform

ENUM MorphologicalTransform

The morphological transformation, possible types are: ERODE, DILATE, OPEN, CLOSE, GRADIENT, TOPHAT and BLACKHAT.

Return values
Name Type Description

imageOut

OBJECT Image

Morphology transformed image

Sample
imageOut = Image.morphology(imageIn, diameterPix, transform)
mosaic()
Short description

Crops an image into a vector of smaller tiles. The mosaic tiles can be specified to overlap. A valid tile must be completely within the source image, i.e., tiles that would partly extend outside the image at the right and bottom borders of the source image are not included in the output vector. The vector of tiles is sorted row wise so that all the tiles covering the uppermost part of the image come first.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image.

tileWidth

INT

The width of a tile in pixels.

tileHeight

INT

The height of a tile in pixels.

xOverlap

INT

Optional overlap between tiles in the x-direction in pixels. Default is no overlap, i.e., 0 pixels.

yOverlap

INT

Optional overlap between tiles in the y-direction in pixels. Default is no overlap, i.e., 0 pixels.

Return values
Name Type Description

imageTiles

OBJECT Image

Vector of image tiles.

xTileCount

INT

Number of tiles in the x-direction.

yTileCount

INT

Number if tiles in the y-direction.

Sample
local imageTiles, nx, ny = Image.mosaic(im, 32, 32)
multiply()
Short description

Multiplies two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate value. The second image is treated as a unit-less modifier and it must therefore have a standard image world coordinate system with pixel sizes all equal to 1 and origins equal to 0. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. Note that it is possible to obtain 0 as result of the multiplication and that such pixels then will be considered as missing data in subsequent processing steps.

Keywords

arithmetic, scale, times

Parameters
Name Type Description

image1

CONST_OBJECT Image

The first source image.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

The product image.

Sample
result = Image.multiply(image1, image2)
multiplyAddConstant()
Short description

Multiplies an image pixelwise by a constant alpha and then adds a second constant beta: alpha*Image + beta. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

arithmetic, scale, offset

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

alpha

FLOAT

The constant to multiply with.

beta

FLOAT

The constant to add.

Return values
Name Type Description

result

OBJECT Image

The resulting image.

Sample
result = Image.multiplyAddConstant(image, alpha, beta)
multiplyAddConstantInplace()
Short description

Inplace version of Image.multiplyAddConstant function which modifies the input image. See base function for full documentation.

Keywords

arithmetic, scale, offset

Parameters
Name Type Description

image

OBJECT Image

The source image. This image is overwritten with the result image.

alpha

FLOAT

The constant to multiply with.

beta

FLOAT

The constant to add.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.multiplyAddConstantInplace(image, alpha, beta)
multiplyConstant()
Short description

Multiplies all pixels in the image with a constant value. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, multiplication of the world z-value is done, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. Note that it is possible to obtain 0 as result of the multiplication and that such pixels then will be considered as missing data in subsequent processing steps.

Keywords

arithmetic, scale, times

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

constant

FLOAT

The constant.

Return values
Name Type Description

result

OBJECT Image

The multiplied image.

Sample
result = Image.multiplyConstant(image, 2.0)
multiplyConstantInplace()
Short description

Inplace version of Image.multiplyConstant function which modifies the input image. See base function for full documentation.

Keywords

arithmetic, scale, times

Parameters
Name Type Description

image

OBJECT Image

The source image. This image is overwritten with the result image.

constant

FLOAT

The constant.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.multiplyConstantInplace(image, 2.0)
multiplyInplace()
Short description

Inplace version of the Image.multiply function which modifies the first input image to contain the product of the input images. See base function for full documentation.

Keywords

arithmetic, scale, times

Parameters
Name Type Description

image1

OBJECT Image

The first source image. This image is overwritten with the product.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.multiplyInplace(image1, image2)
normalize()
Short description

Scales the raw pixel values linearly so that all pixels fit into a given range (lowerBound, upperBound). Keeps the world values constant. Target bounds outside the representable range of the image type are accepted. In that case, pixel values are clamped to the representable range. Image world coordinate system handling: The world coordinate system of the output image along the value axis z is chosen such that the world pixel values remains unchanged unless clamping occurs. For integer type images, rounding to integer raw pixel values will change the world values slightly. Other meta data are copied from the input image. Missing data handling: Pixels with missing data remain marked as missing in the output. For images with the missing data flag set, raw pixel values are clamped to 1 instead of 0 to avoid introducing more pixels marked as missing.

Keywords

contrast, intensity, scale, stretch, equalize

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, int8, int16, int32, float32 and float64.

lowerBound

FLOAT

Lower bound (raw pixel value). Default value is minimum value of underlying datatype.

upperBound

FLOAT

Upper bound (raw pixel value). Default value is maximum value of underlying datatype.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.

Return values
Name Type Description

normalizedImage

OBJECT Image

Normalized image

Sample
normalizedImage = Image.normalize(image)
pad()
Short description

Image padding, adds a border to the image. Image world coordinate system handling: The image world coordinate system is used to update the output image origin, it is calculated as follows: (Oxout, Oyout, Ozout) = (Oxin - pixelSizeX * leftPaddingPix, Oyin - pixelSizeY * topPaddingPix, Ozin), the world pixel sizes remain the same. The boundary paddings are in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not use the missing data flag. If the padding contains zeros it will be treated as missing data if the flag is on.

Keywords

replicate, extend

Parameters
Name Type Description

imageIn

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB.

topPaddingPix

INT

The top padding in pixels

bottomPaddingPix

INT

The bottom padding in pixels

leftPaddingPix

INT

The left padding in pixels

rightPaddingPix

INT

The right padding in pixels

borderType

ENUM BorderType

The border type to use for the padding, currently CONSTANT, REPLICATE, REFLECT and WRAP are available. If the border type is not CONSTANT the padding value is not used.

intensity

FLOAT

The padding intensity. In case the image type is RGB then an array of 3 elements (one per channel) must be provided. If the border type is not CONSTANT this value does not need to be specified.

Return values
Name Type Description

imageOut

OBJECT Image

Padded Image

Sample
imageOut = Image.pad(imageIn, topPaddingPix, bottomPaddingPix, leftPaddingPix, rightPaddingPix, borderType, intensity)
pow()
Short description

Applies an exponent to the value at each pixel. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel data type respectively. Image world coordinate system handling: The z-scale of the image is considered, but the operation is not implemented for images with z-origin different from 0.0. The image metadata from the input image is copied to the output image. Missing data handling: In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

arithmetic, cube, exp, exponent, inverse, invert, sqr, sqrt, square, power

See also

Image.powInplace

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image.

exponent

FLOAT

The exponent.

Return values
Name Type Description

result

OBJECT Image

The processed image.

Sample
result = Image.pow(image, exponent)
powInplace()
Short description

Inplace version of the Image.pow function which modifies the input image. See base function for full documentation.

Keywords

arithmetic, cube, exp, exponent, inverse, invert, sqr, sqrt, square, power

See also

Image.pow

Parameters
Name Type Description

image

OBJECT Image

The source image. This image is overwritten with the result image.

exponent

FLOAT

The exponent.

Return values
Name Type Description

result

OBJECT Image

A reference to the result image.

Sample
Image.powInplace(image, exponent)
renderPlane()
Short description

Renders a plane to an image, clamping values to the representable range of the image. The output image is of the same type as the input image. Image world coordinate system handling: The surface is rendered in the world space defined by the reference image, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the reference image is copied to the output image. Missing data handling: The missing data flag of the reference image is copied to the output image. If the flag is set, raw pixel values are clamped to 1 instead of 0 to avoid generating pixels with missing data.

Keywords

draw

Parameters
Name Type Description

image

CONST_OBJECT Image

The reference image defining the output image size, type and coordinate system.

plane

CONST_OBJECT Shape3D

The plane to render, should be a plane shape.

Return values
Name Type Description

renderedImage

OBJECT Image

The image with the rendered plane. Nil if an error occurred.

Sample
renderedImage = Image.renderPlane(image, plane)
renderPlaneInplace()
Short description

Inplace version of the Image.renderPlane function which modifies the input image by adding the value of a given plane. See base function for full documentation.

Keywords

draw

Parameters
Name Type Description

image

OBJECT Image

Reference input image. This image is overwritten with the result image.

plane

CONST_OBJECT Shape3D

The plane to render, must be a Shape3D plane.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.renderPlaneInplace(image, plane)
renderText()
Short description

Renders text into an image by modifying the pixel values. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The font parameters and text position are in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not use the missing data flag.

Keywords

characters, letters, draw

Parameters
Name Type Description

image

OBJECT Image

The image to render the text into. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB.

text

STRING

The characters that cannot be rendered using the specified font are replaced by question marks.

positionWorld

CONST_OBJECT Point

The position of the text inside the image, in world coordinates. The text is aligned to the bottom-left corner.

fontSizePix

INT

The font size in pixels.

fontThicknessPix

INT

The font line thickness radius in pixels. To calculate the overall thickness the following equation can be used: thickness=(fontThicknessPix*2+1).

value

FLOAT

The text (intensity/color) value. In case the image type is RGB then an array of 3 elements (one per channel) must be provided.

Return values
Name Type Description

image

OBJECT Image

Image with rendered text

Sample
image = Image.renderText(image, text, positionWorld, fontSizePix, fontThicknessPix, value)
renderTextInplace()
Short description

Inplace version of the Image.renderText function that modifies the input image. See base function for full documentation.

Keywords

characters, letters, draw

Parameters
Name Type Description

image

OBJECT Image

The image to render the text into. This image is overwritten with the rendered text. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB.

text

STRING

The characters that cannot be rendered using the specified font are replaced by question marks.

positionWorld

CONST_OBJECT Point

The position of the text inside the image, in world coordinates. The text is aligned to the bottom-left corner.

fontSizePix

INT

The font size in pixels.

fontThicknessPix

INT

The font line thickness radius in pixels. To calculate the overall thickness the following equation can be used: thickness=(fontThicknessPix*2+1).

value

FLOAT

The text (intensity/color) value. In case the image type is RGB then an array of 3 elements (one per channel) must be provided.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.renderTextInplace(image, text, positionWorld, fontSizePix, fontThicknessPix, value)
replace()
Short description

Replaces the image content in a specified region with the content of another image. The images must have the same pixel type. Image world coordinate system handling: The world coordinate systems of the input images are not used. The output will have the same coordinate system as the first input image. Missing data handling: Raw pixel values are copied as they are. If there are missing data within the region in the replacing image, the source image pixels will be replaced by missing data.

Parameters
Name Type Description

sourceImage

CONST_OBJECT Image

Base image onto which the other image is painted.

replacingImage

CONST_OBJECT Image

The image containing the information to replace with.

region

CONST_OBJECT Image.PixelRegion

The region to replace.

Return values
Name Type Description

result

OBJECT Image

The composed image.

Sample
local result = Image.replace(sourceImage, replacingImage, region)
replaceInplace()
Short description

Inplace version of the Image.replace function which modifies the first input image by replacing pixel values with pixel values from another image. See base function for full documentation.

Parameters
Name Type Description

sourceImage

OBJECT Image

Base image onto which the other image is painted.

replacingImage

CONST_OBJECT Image

The image containing the information to replace with.

region

CONST_OBJECT Image.PixelRegion

The region to replace.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
local result = Image.replaceInplace(sourceImage, replacingImage, region)
resize()
Short description

Resizes an image to a given size in pixels. Different interpolation methods can be used. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

decimate, downsample, resample, subsample, transform, upsample, scale

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image

width

INT

The width of the result

height

INT

The height of the result.

method

ENUM InterpolationMethod

The resampling method. Default is LINEAR.

Return values
Name Type Description

resizedImage

OBJECT Image

Image with new size.

Sample
resizedImage = Image.resize(image, 300, 400, "LINEAR")
resizeScale()
Short description

Resizes an image by a scale factor. Different interpolation methods can be used. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

decimate, downsample, resample, subsample, transform, upsample, scale

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image

fx

FLOAT

Scaling factor along the x-axis.

fy

FLOAT

Scaling factor along the y-axis. Optional, if omitted the same as the x-scale is used.

method

ENUM InterpolationMethod

The resampling method. Default is LINEAR.

Return values
Name Type Description

resizedImage

OBJECT Image

Image with new size.

Sample
resizedImage = Image.resizeScale(image, 1.5, 1.5, "LINEAR")
rotate()
Short description

Rotates an image around the center of the image. Optionally a different origin of rotation can be specified. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image

rotationRad

FLOAT

Rotation in radians. As the image has a left-handed coordinate system, a positive rotation is in a counter clockwise direction.

origin

CONST_OBJECT Point

Optional origin of rotation if other than center of image. Represented as a 2D Point type.

method

ENUM InterpolationMethod

The resampling method.

grid

ENUM OutputGrid

The pixel grid to use for the output, default is SAME, the same as the input image.

Return values
Name Type Description

rotatedImage

OBJECT Image

The rotated image.

Sample
rotatedImage = Image.rotate(image, rotationRad)
rotate90()
Short description

Rotates an image +90, -90 or 180 degrees. A positive rotation is in the clockwise direction. The pixels are rearranged and no interpolation takes place, making the operation faster than a general rotation. Image world coordinate system handling: For plus and minus 90 degree rotations, the x- and y-pixel sizes are swapped so that the width and height are also swapped. The image origin is copied from the input image. Missing data handling: Missing data is rotated in the same way as the input image.

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image

rotationSteps

INT

The number of 90-degree steps to rotate the image in, e.g. -1, 1 or 2. Other integers are allowed, representing the same rotations. A positive rotation is in a clockwise direction.

Return values
Name Type Description

rotatedImage

OBJECT Image

The rotated image.

Sample
rotatedImage = Image.rotate90(image, rotationSteps)
save()
Short description

Saves an image to the specified file path. Overwrites the file if it already exists. Supported pixel types are: UINT8, UINT16, INT8, INT16, INT32, FLOAT32 and FLOAT64. The format is defined by the file extension: .bmp: Bitmap, no data compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are not saved. .png: PNG, lossless data compression. (Compression level can be controlled by compression parameter. Allowed values are "0" to "9". Default is "6".) Image origin, pixel size and missing data flag are not saved. For pixel types INT8, INT16, INT32, FLOAT32 and FLOAT64 the values are clamped to 0-255. .jpg: JPEG, lossy data compression. Not supported on all devices. (Quality can be controlled by compression parameter. Allowed values are "0" to "100". Default is "95") Image origin, pixel size and missing data flag are not saved. .json: JSON, no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved. .msgpack: MessagePack, no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved.

See also

File, Object.save

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to save.

filepath

STRING

The path and name of the file to write the image to.

compression

STRING

Optional parameters controlling compression ratio for certain file formats.

Return values
Name Type Description

success

BOOL

Returns true on success.

Sample
Image.save(image, "private/image.bmp")
setAll()
Short description

Sets all raw pixel values in an image to the specified value. Currently only supports scalar pixel types, i.e., not RGB. Pixels with missing data are also set. Setting all pixels to zero on an image with the global missing data flag set, all pixels will be marked as missing.

See also

Image.setPixel

Parameters
Name Type Description

image

OBJECT Image

The image.

value

FLOAT

The raw pixel value to set.

Sample
Image.setAll(image, 0.0)
setColumn()
Short description

Fills in a column of an image with the value(s) provided. Note that this function operates inplace. If a scalar value is provided, all rows from startRow to the image height will be filled with the value. If the provided value(s) is a vector of length N, N rows will be filled with these values starting at row startRow. Coordinate system handling: The image world coordinate system is only considered along the value range. Missing data handling: A missing data image may be used as the target image. Values evaluating to the origin in z will become missing in the target.

Parameters
Name Type Description

image

OBJECT Image

The target image. All pixel types except RGB are supported.

values

FLOAT

The source profile.

column

INT

Index of column to fill, zero-based.

startRow

INT

The first row index to fill, zero-based. If no index is given 0 will be used.

Return values
Name Type Description

success

BOOL

True if values could be set.

Sample
local success = Image.setColumn(image, values, column, startRow)
setColumnProfile()
Short description

Fills in a column of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image column starting at row startRow. The number of values set are equal to the length of the profile. Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels. Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.

Parameters
Name Type Description

image

OBJECT Image

The target image. All pixel types except RGB are supported.

profile

CONST_OBJECT Profile

The source profile.

column

INT

Index of column to fill, zero-based.

startRow

INT

The first row index to fill, zero-based. If no index is given 0 will be used.

Return values
Name Type Description

success

BOOL

True if values could be set.

Sample
local success = Image.setColumnProfile(image, profile, column, startRow)
setMissingDataFlag()
Short description

Sets the missing data setting in the image. 0 means no missing data handling, 1 means that the value 0 is treated as missing data.

Parameters
Name Type Description

image

OBJECT Image

missingDataFlag

INT

0 means no missing data handling, 1 means that the value 0 is treated as missing data.

Sample
Image.setMissingDataFlag(image, 1)
setOrigin()
Short description

Sets the origin of the image world coordinate system in the image. The origin corresponds to the image world coordinate of the top-left pixel. If a 2D point is provided, the origin is unchanged in the z-direction.

Parameters
Name Type Description

image

OBJECT Image

origin

CONST_OBJECT Point

A 3D point describing the world coordinate of the top-left image pixel.

Return values
Name Type Description

success

BOOL

Returns true if successfully set the origin.

Sample
local success = Image.setOrigin(image, origin)
setOriginZ()
Short description

Sets the z-origin of the image world coordinate system in the image.

Parameters
Name Type Description

image

OBJECT Image

Image object to update.

originZ

FLOAT

The new z-origin.

Sample
Image.setOriginZ(image, originZ)
setPixel()
Short description

Set the raw pixel value or a vector of pixel values in an image at position(s) (x,y) to the given raw pixel value. For monochrome image types this is a single float value, for RGB24 a vector of three float values in the order red, green, blue.

Parameters
Name Type Description

image

OBJECT Image

The image to set the pixels to

x

INT

The x coordinate, or a vector of x coordinates, of the pixel(s) to set.

y

INT

The y coordinate, or a vector of y coordinates, of the pixel(s) to set.

value

FLOAT

The raw pixel value, or a vector of RGB values, to set.

Sample
Image.setPixel(image, 5, 6, 127)
Image.setPixel(imageRGB, {5, 5}, {6, 7}, {0, 127, 255})
setPixelSize()
Short description

Sets the pixel size in world coordinates. If the size in the Z direction is omitted, the Z size is unchanged.

Parameters
Name Type Description

image

OBJECT Image

sizeX

FLOAT

The size of a pixel in the X dimension in world coordinate units.

sizeY

FLOAT

The size of a pixel in the Y dimension in world coordinate units.

sizeZ

FLOAT

The size of a pixel in the Z dimension in world coordinate units (optional).

Sample
Image.setPixelSize(image, sizeX, sizeY, sizeZ)
setPixelSizeZ()
Short description

Sets the pixel size in the z-dimension in world coordinates, e.g., the number of millimeters each pixel value integer increment corresponds to.

Parameters
Name Type Description

image

OBJECT Image

sizeZ

FLOAT

The size/scale along the z-dimension.

Sample
Image.setPixelSizeZ(image, sizeZ)
setRow()
Short description

Fills in a row of an image with the value(s) provided. Note that this function operates inplace. If a scalar value is provided, all columns from startColumn to the image width will be filled with the value. If the provided value(s) is a vector of length N, N columns will be filled with these values starting at column startColumn. Coordinate system handling: The image world coordinate system is only considered along the value range. Missing data handling: A missing data image may be used as the target image. Values evaluating to the origin in z will become missing in the target.

Parameters
Name Type Description

image

OBJECT Image

The target image. All pixel types except RGB are supported.

values

FLOAT

The source data.

row

INT

Index of row to fill, zero-based.

startColumn

INT

The first column index to fill, zero-based. If no index is given 0 will be used.

Return values
Name Type Description

success

BOOL

True if values could be set.

Sample
local success = Image.setRow(image, values, row, startColumn)
setRowProfile()
Short description

Fills in a row of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image row starting at column startColumn. The number of values set are equal to the length of the profile. Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels. Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.

Parameters
Name Type Description

image

OBJECT Image

The target image. All pixel types except RGB are supported.

profile

CONST_OBJECT Profile

The source profile.

row

INT

Index of row to fill, zero-based.

startColumn

INT

The first column index to fill, zero-based. If no index is given 0 will be used.

Return values
Name Type Description

success

BOOL

True if values could be set.

Sample
local success = Image.setRowProfile(image, profile, row, startColumn)
sobel()
Short description

Applies the standard 3x3 Sobel filter operator to find gradients and edges in the x- and y-directions. Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.

Keywords

convolve, derivative, gradient, edge

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, int16, float32 and float64.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Pixel values outside the region are undefined.

Return values
Name Type Description

gx

OBJECT Image

Output image with gradient x.

gy

OBJECT Image

Output image with gradient y.

Sample
gx, gy = Image.sobel(image)
sobelMagnitude()
Short description

Calculates the magnitude of the standard 3x3 Sobel operator gradient responses dx and dy to find edges in the input image. Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.

Keywords

convolve, derivative, gradient, edge

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image. Supported image types are uint8, uint16, uint32, int8, int16, int32, float32 and float64.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.

metric

ENUM MetricType

Select if the faster abs(dx)+abs(dy) or the more precise sqrt(dx2+dy2) should be used. Default is 'ABS'.

Return values
Name Type Description

imageMag

OBJECT Image

Output image with gradient magnitude.

Sample
imageMag = Image.sobelMagnitude(image)
splitRGB()
Short description

Splits an RGB image into the individual R, G, B color components. The input RGB image must be of 8-bit RGB type.

Keywords

color

Parameters
Name Type Description

imageRGB

CONST_OBJECT Image

RGB image (8-bit) to convert.

Return values
Name Type Description

imageR

OBJECT Image

Red component as image.

imageG

OBJECT Image

Green component as image.

imageB

OBJECT Image

Blue component as image.

Sample
imageR, imageG, imageB = Image.splitRGB(imageRGB)
subtract()
Short description

Subtracts two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. For unsigned integer types it can be useful to first apply Image.adjustOriginZ() to image1 to avoid clamping the results to 0. For images A, B subtracting B from A would cause clamping when values in B are larger than those in A by such a large amount that the difference exceeds the Z-origin of A. By adjusting the origin of A to a smaller value this can be remedied. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.

Keywords

arithmetic, difference, minus

Parameters
Name Type Description

image1

CONST_OBJECT Image

The first source image.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

The difference image.

Sample
result = Image.subtract(image1, image2)
subtractInplace()
Short description

Inplace version of the Image.subtract function which modifies the first input image to contain the difference of the input images. See base function for full documentation.

Keywords

arithmetic, difference, minus

Parameters
Name Type Description

image1

OBJECT Image

The first source image. This image is overwritten with the difference.

image2

CONST_OBJECT Image

The second source image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.subtractInplace(image1, image2)
subtractPlane()
Short description

Subtracts a plane from an image. For every pixel, the corresponding plane z-value is subtracted. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. By setting autoAdjustOriginZ true for unsigned integer data, the origin of the result image will be adjusted to avoid clamping at zero. Using automatic origin adjustment on a partial region of the image will not compensate the pixel values outside the region for the new origin, such pixels will appear with an offset in global coordinates. Image world coordinate system handling: The plane is interpreted in world space and subtracted from the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Keywords

gradient, ramp

Parameters
Name Type Description

image

CONST_OBJECT Image

The image.

plane

CONST_OBJECT Shape3D

The plane to subtract, must be a Shape3D plane.

region

CONST_OBJECT Image.PixelRegion

Region of the image where the plane should be subtracted, default is the full image. An empty region or nil are interpreted as the full image.

autoAdjustOriginZ

BOOL

Flag indicating if the origin of the output image should be adjusted to avoid clamping at zero. Default is false, using the same origin as the input image.

Return values
Name Type Description

resultImage

OBJECT Image

The image with the subtracted plane. Nil if an error occurred.

Sample
resultImage = Image.subtractPlane(image, plane, region, autoAdjustOriginZ)
subtractPlaneInplace()
Short description

Inplace version of the Image.subtractPlane function which modifies the input image by subtracting the value of a given plane. See base function for full documentation.

Keywords

gradient, ramp

Parameters
Name Type Description

image

OBJECT Image

The source image. This image is overwritten with the result image.

plane

CONST_OBJECT Shape3D

The plane to subtract, must be a Shape3D plane.

region

CONST_OBJECT Image.PixelRegion

Region of the image where the plane should be subtracted, default is the full image. An empty region or nil are interpreted as the full image.

autoAdjustOriginZ

BOOL

Flag indicating if the origin of the output image should be adjusted to avoid clamping at zero. Default is false, using the same origin as the input image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.subtractPlaneInplace(image, plane, region, autoAdjustOriginZ)
subtractProfile()
Short description

Returns the image with the profile subtracted from all rows or all columns depending on the dimension argument. The dimension argument is optional and if not provided processing is done row by row. Image world coordinate system handling: The input profile is in world coordinates. The result image will have originZ set to zero. Missing data handling: For missing data in the image, the pixels with missing data will still be zero. For missing data in the profile, the image data will be unchanged. If missing data note that the minimum value is always 1 for valid pixels.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image.

profile

CONST_OBJECT Profile

The profile.

dimension

ENUM ProcessingDimension

Optional processing dimension (row/column).

Return values
Name Type Description

result

OBJECT Image

Image with profile subtracted along processing dimension.

Sample
result = Image.subtractProfile(image, profile, dimension)
subtractProfileInplace()
Short description

Inplace version of the Image.subtractProfile function that modifies the input image. See base function for full documentation.

Parameters
Name Type Description

image

OBJECT Image

The image. This image is overwritten with the result image.

profile

CONST_OBJECT Profile

The profile.

dimension

ENUM ProcessingDimension

Optional processing dimension (row/column).

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.subtractProfileInplace(image, profile, dimension)
thin()
Short description

Applies a morphological thinning, also known as skeletonization, using the Guo-Hall algorithm. It is typically performed on an already binarized input image. Zeros in the input image are be interpreted as background pixels. Note: The algorithm can be slow for large images with many non-zeros (large binary objects). Consider operating on regions of interest if possible. The output is a binary image with the skeleton indicated by pixels set to the maximum value of the pixel type, e.g., 255 for the uint8 type. Image world coordinate system handling: The image world coordinate system is not considered in this function. The output image inherits the x,y origin and x,y pixelsize, but the z-origin is reset to 0 and z-pixelsize to 1. Missing data handling: The missing data flag is reset by this function as the output is a binary image.

Keywords

morphology, skeleton

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image, expected to be binary. Supported image types are uint8 and uint16.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small.

Return values
Name Type Description

skeletonImage

OBJECT Image

Skeleton image.

Sample
skeletonImage = Image.thin(image)
threshold()
Short description

Threshold the image by keeping all pixels with a value between lowerThreshold and upperThreshold (inclusive). Return the result as a PixelRegion object. Image world coordinate system handling: The input thresholds are interpreted in the image world coordinate system considering the z-origin and z-pixelsize, e.g., in millimeter scale if the image would represent a range image with z-origin different from 0 of a z-pixelsize different from 1. A conversion is done within the function to raw pixel value thresholds. Missing data handling: Missing data pixels are excluded from the output PixelRegion object.

Keywords

background, blob, foreground, region, segmentation

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image.

lowerThreshold

FLOAT

Lower threshold. Expressed in image world coordinates if applicable.

upperThreshold

FLOAT

Upper threshold. Optional, default is no upper threshold (only include pixels larger than the lower threshold)

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

Pixel region containing all pixels with value between the thresholds.

Sample
region = Image.threshold(image, 1, 255) -- Gets a region containing all non-zero values of an uint8 image
thresholdCompare()
Short description

Threshold an image by pixelwise comparison with a reference image. All pixels with a value greater than or equal to the corresponding reference image value are included in the output PixelRegion object. An optional margin (positive or negative) may be provided, adjusting the reference image values prior to the comparison. A larger positive margin results in fewer included pixels. The optional flag findBright may be set to false, returning the region where the image is lower/darker than the reference image. A region of interest can be provided, limiting the processing to that region. The images must be of the same pixel type and be of equal size. This function gives a PixelRegion objects as output, to get a binary image as output use binarizeCompare instead. Image world coordinate system handling: To allow for an efficient comparison, the z-pixelsizes of the input images must be equal but the z-offsets may differ. The margin parameter is interpreted in image world coordinates, e.g., as a millimeter margin if the input is a range image. Missing data handling: Missing data pixels are excluded from the output PixelRegion object.

Keywords

adaptive, background, blob, foreground, region, segmentation, binarize

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image to threshold.

referenceImage

CONST_OBJECT Image

Reference image to compare the input image with.

marginWorld

FLOAT

Optional margin added to the reference image. Default value is 0.

findBright

BOOL

Optional flag indicating if pixels brighter/higher or darker/lower than the reference image should be included. Default is true, returning brighter pixels.

regionOfInterest

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. The default region is the entire image.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

PixelRegion object containing all pixels passing the comparison operation.

Sample
region = Image.thresholdCompare(image, referenceImage, marginWorld, findBright, regionOfInterest)
thresholdPlane()
Short description

Thresholds the image by keeping all pixels with a world value between lowerThreshold and upperThreshold relative to the provided plane (inclusive). Returns the result as a PixelRegion object. Thresholding values strictly below or above the reference plane is also supported, using relative thresholds with the same sign. Image world coordinate system handling: The plane is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. Thresholds are interpreted in the world coordinate system. Missing data handling: No pixel marked as missing is included in the output region.

Keywords

adaptive, background, blob, foreground, region, segmentation, binarize

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image

lowerThreshold

FLOAT

Lower threshold relative to plane.

upperThreshold

FLOAT

Upper threshold relative to plane.

plane

CONST_OBJECT Shape3D

The plane, represented as a Shape3D, to which the lower and upper thresholds are related. The shape type must be a plane.

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small.

Return values
Name Type Description

thresholdedRegion

OBJECT Image.PixelRegion

Pixel region containing all pixels with value between the thresholds relative to the plane.

Sample
thresholdedRegion = Image.thresholdPlane(image, lowerThreshold, upperThreshold, plane, region)
toGray()
Short description

Converts an RGB image into a gray value image.

Keywords

RGB, grey

Parameters
Name Type Description

imageRGB

CONST_OBJECT Image

RGB image (8-bit) to convert.

Return values
Name Type Description

imageGray

OBJECT Image

Gray value image of uint8 pixel type.

Sample
imageGray = Image.toGray(imageRGB)
toHSV()
Short description

Converts an RGB image into individual HSV color space components. The Hue-component is usually represented as an angle in the interval [0,360], but to fit in a uint8 image the value is divided by 2 to be in the interval [0,180].

Keywords

HSL, RGB, hue, saturation, color

Parameters
Name Type Description

imageRGB

CONST_OBJECT Image

RGB image (8-bit) to convert.

Return values
Name Type Description

imageH

OBJECT Image

Hue image, uint8 pixel type and in range [0,180]

imageS

OBJECT Image

Saturation image, uint8 pixel type and in range [0,255]

imageV

OBJECT Image

Value image, uint8 pixel type and in range [0,255]

Sample
imageH, imageS, imageV = Image.toHSV(imageRGB)
toLab()
Short description

Converts an RGB image into individual Lab color space components.

Keywords

RGB, color

Parameters
Name Type Description

imageRGB

CONST_OBJECT Image

RGB image (8-bit) to convert.

Return values
Name Type Description

imageL

OBJECT Image

Lightness image, uint8 pixel type and in range [0,255]

imageA

OBJECT Image

'a' color component image, uint8 pixel type and in range [1,255]

imageB

OBJECT Image

'b' color component image, uint8 pixel type and in range [1,255]

Sample
imageL, imageA, imageB = Image.toLab(imageRGB)
toMatrix()
Short description

Creates a matrix from a monochrome image. Each entry in the matrix corresponds to the pixel value scaled by the image world Z coordinates. Missing data is set to NaN in the matrix.

Parameters
Name Type Description

inputImage

CONST_OBJECT Image

The input image.

Return values
Name Type Description

matrix

OBJECT Matrix

The matrix with the image content.

Sample
local matrix = Image.toMatrix(inputImage)
toPixelCoordinate()
Short description

Converts an image world coordinate to a pixel coordinate.

Parameters
Name Type Description

image

CONST_OBJECT Image

worldCoordinate

CONST_OBJECT Point

The world coordinate point.

Return values
Name Type Description

pixelCoordinate

OBJECT Point

Returns the pixel coordinate.

Sample
local pixelCoordinate = Image.toPixelCoordinate(image, worldCoordinate)
toPixelZ()
Short description

Converts a z world coordinate value to a raw pixel value using the image world coordinate system supplied by the input reference image. The mapping pixelValue = (worldZCoordinate - originZ)/pixelSizeZ is made.

Parameters
Name Type Description

refImage

CONST_OBJECT Image

Image carrying the image world coordinate system. No other information from the image is used.

worldZCoordinate

FLOAT

World z coordinate(s), e.g., millimeters.

Return values
Name Type Description

pixelValue

FLOAT

Raw pixel value(s).

Sample
local pixelValue = Image.toPixelZ(image, worldZCoordinate)
toPointCloud()
Short description

Creates a pointcloud from image(s). Typically one heightmap input image is used in which the pixel pitch is constant in each dimension. The alternative use cases are to supply separate images for either x and z or for x, y and z coordinates. In total there are three ways this can be used: 1. Image.toPointCloud(range, true/false, intensity, region) 2. Image.toPointCloud({X, Z}, true/false, intensity, region) 3. Image.toPointCloud({X, Y, Z}, true/false, intensity, region) In case 1 the pixel sizes and origin of the range image is used to create the X and Y coordinates. In case 2 the pixel sizes and origin of of Z is used to create the Y coordinates in the output. In case 3 all positions are uniquely determined by the input images X, Y and Z. Pixel sizes and origin in the input images are unused. The intensity and region inputs are optional and can be used to set the intensity of the output pointcloud and to remove points respectively. Image world coordinate system handling: in general the image world coordinate system is used to create the pointcloud, i.e. the (x, y, z)-pixel sizes and origins are used to create the (x, y, z)-components of the pointcloud. For details see the longer text above. Missing data handling: For images with missing data it is possible to select to keep or remove the missing points. If missing points are kept they are marked as such in the pointcloud and will be black in intensity. If they are removed the grid structure of the image is lost and the point cloud will be considered an unordered point cloud.

Keywords

extrude

Parameters
Name Type Description

image

CONST_OBJECT Image

The source image(s) with range/depth information. Either one range image or 3 coordinate images (X, Y and Z).

removeMissing

BOOL

Select if points that are missing data should be removed or not. For images without missing data this has no effect. Default is false.

intensity

CONST_OBJECT Image

Optional uint8 image that will be used for intensity information for each point. The pixel values are divided by 255 to create a number in the range [0,1] for the pointcloud intensity.

region

CONST_OBJECT Image.PixelRegion

Optional PixelRegion. If supplied, only points within the region are converted.

Return values
Name Type Description

pointcloud

OBJECT PointCloud

The resulting pointcloud.

Sample
local pointcloud = Image.toPointCloud(image, removeMissing, intensity, region)
toRGB()
Short description

Creates an RGB image from three grayscale images. The input images must be of uint8 type.

Keywords

color

Parameters
Name Type Description

imageR

CONST_OBJECT Image

Gray value image of uint8 type.

imageG

CONST_OBJECT Image

Gray value image of uint8 type.

imageB

CONST_OBJECT Image

Gray value image of uint8 type.

colorSpace

ENUM ColorSpace

The color space the input images represent.

Return values
Name Type Description

imageRGB

OBJECT Image

RGB image (8-bit).

Sample
imageRGB = Image.toRGB(imageR, imageG, imageB, colorSpace)
toSquarePixels()
Short description

Resizes an image to have square pixels, i.e., to have equal pixelsizes in the x and y dimensions. Having square pixels is sometimes required for further processing. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, will be copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

resample, scale, transform, anisotropic

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image

upsample

BOOL

Select if to upsample one axis or downsample the other. Default is false.

method

ENUM InterpolationMethod

The resampling method. Default is LINEAR.

Return values
Name Type Description

squarePixelImage

OBJECT Image

Image with square pixels.

Sample
squarePixelImage = Image.toSquarePixels(image)
toString()
Short description

Gets a user-friendly string description of the image, containing all properties but no actual pixel values.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to describe.

Return values
Name Type Description

str

STRING

User-friendly description of the image.

Sample
str = Image.toString(image)
toType()
Short description

Converts an image to a new image of specified pixel type. The raw pixel values are casted and there may be underflow/overflow effects when casting to a type of lower capacity. For example, the value 256 in a uint16 image will overflow to 0 if converted to a uint8 type. To avoid such effects, clamp the input pixel values to the min and max values of the target pixel type. Supports only monochrome image types, for the RGB24 type there are more specific conversion functions toGray() and toRGB().

Parameters
Name Type Description

image

CONST_OBJECT Image

The image to be converted.

type

ENUM ImageType

The pixel type, e.g., UINT8, INT16, FLOAT64).

Return values
Name Type Description

convertedImage

OBJECT Image

Returns the image of specified type or nil.

Sample
local convertedImage = Image.toType(image, "UINT8")
toWorldCoordinate()
Short description

Converts a pixel coordinate to an image world coordinate.

Parameters
Name Type Description

image

CONST_OBJECT Image

The image

pixelCoordinate

CONST_OBJECT Point

The pixel coordinate point.

Return values
Name Type Description

worldCoordinate

OBJECT Point

Returns the world coordinate.

Sample
local worldCoordinate = Image.toWorldCoordinate(image, pixelCoordinate)
toWorldZ()
Short description

Converts a pixel raw value to a z world coordinate value using the image world coordinate system supplied by the input reference image. The mapping worldZCoordinate = pixelValue*pixelSizeZ + originZ is made.

Parameters
Name Type Description

image

CONST_OBJECT Image

Image carrying the image world coordinate system. No other information from the image is used.

pixelValue

FLOAT

Raw pixel value(s).

Return values
Name Type Description

worldZCoordinate

FLOAT

World z coordinate(s), e.g., millimeters.

Sample
local worldZCoordinate = Image.toWorldZ(image, pixelValue)
transform()
Short description

Applies a linear geometric transform to an image. The result image uses the same pixel grid as the input image, if the SAME output grid is selected. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

linear, rotate, scale, shear, shift, warp

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image.

transform

CONST_OBJECT Transform

A linear transform defined by a Transform object.

method

ENUM InterpolationMethod

The resampling method. Default is NEAREST.

grid

ENUM OutputGrid

The pixel grid to use for the output, default is SAME, the same as the input image.

Return values
Name Type Description

transformedImage

OBJECT Image

Transformed image.

Sample
transformedImage = Image.transform(image, transform, method)
transformInto()
Short description

Applies a linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. The pixel grid and coordinate system of the destination image is used for transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes of the output image - The world origin of the output image All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image. Image world coordinate system handling: If the image or destination image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is kept in the destination image and the transformed image is painted onto this coordinate system. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image. The missing data flags of the input and destination images must match.

Keywords

linear, rotate, scale, shear, shift, warp

Parameters
Name Type Description

sourceImage

CONST_OBJECT Image

Source image.

transform

CONST_OBJECT Transform

A linear transform defined by a Transform object.

destinationImage

OBJECT Image

Destination image, the output will be placed into this image. The image size, pixels sizes and world origin from this image are used.

method

ENUM InterpolationMethod

The resampling method. Default is NEAREST.

Return values
Name Type Description

transformedImage

OBJECT Image

A reference to the input destinationImage. Nil on failure.

Sample
transformedImage = Image.transformInto(sourceImage, transform, destinationImage, method)
transformInto3D()
Short description

Applies a 3D linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. Compared to the transformInto function, this function adds the possibility for 3D tilts. The function is typically used for heightmap image data. The pixel grid and coordinate system of the destination image are used for the transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes of the output image - The world origin of the output image All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image. Image world coordinate system handling: If the image or reference image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the reference image and the transformed image is repainted onto this coordinate system. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Keywords

linear, rotate, scale, shear, shift, warp

Parameters
Name Type Description

sourceImage

CONST_OBJECT Image

Source image.

transform

CONST_OBJECT Transform

A linear affine 3D transform defined by a Transform object.

destinationImage

OBJECT Image

Destination image, the output will be placed into this image. The image size, pixels sizes and world origin from this image are used.

method

ENUM InterpolationMethod

The resampling method. Default is NEAREST.

splatX

INT

The influence distance of a source point in the target image x direction. Default is 3.

splatY

INT

The influence distance of a source point in the target image y direction. Defaults to splatX if unset.

clearTarget

BOOL

Select if the destinationImage should be reset to missing data before transforming the source image into it.

Return values
Name Type Description

transformedImage

OBJECT Image

A reference to the input destinationImage. Nil on failure.

Sample
transformedImage = Image.transformInto3D(sourceImage, transform, destinationImage, method)
warpSector()
Short description

Warps the inner area of a sector shape to a rectilinear Cartesian grid.

Keywords

rectify, unwrap

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image.

sector

CONST_OBJECT Shape

A sector shape defining the area in the source image to warp from.

interpolation

ENUM InterpolationMethod

Interpolation method to use. Currently only LINEAR is available.

Return values
Name Type Description

warpedImage

OBJECT Image

The warped image, or nil on failure.

Sample
warpedImage = Image.warpSector(image, sector, interpolation)

Image.Calibration

Overview

Image.Calibration.CameraModel

Short description

Calibration result object of single camera. These objects can be stored to and loaded from file. The results of the camera calibration satisfy the camera transformation equation from world to the image coordinate system: xp = KD([R|t] * X) K = [fx s cx, 0 fy cy, 0 0 1] D = Brown–Conrady lens model: k1, k2, p1, p2, k3 R = [r11 r12 r13, r21 r22 r23, r31 r32 r33] t = [tx ty tz]^T

Functions

create()
Short description

Create a instance for the calibration result handling

Return values
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The calibration result object instance.

Sample
cameraModel = Image.Calibration.CameraModel.create()
getCalibrationImageSize()
Short description

Get the image size for which the calibration is valid.

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

imageWidth

INT

The image width for which the calibration is valid.

imageHeight

INT

The image height for which the calibration is valid.

Sample
local imageWidth, imageHeight = Image.Calibration.CameraModel.getCalibrationImageSize(cameraModel)
getCameraID()
Short description

Get the unique camera identifier.

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

cameraID

STRING

The unique camera identifier.

Sample
local cameraID = Image.Calibration.CameraModel.getCameraID(cameraModel)
getEulerAngles()
Short description

Get the Euler angle representation (yaw, pitch, roll) of the transform into camera coordinates (in degree).

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

yaw

FLOAT

The rotation around x-axis in degree.

pitch

FLOAT

The rotation around y-axis in degree.

roll

FLOAT

The rotation around z-axis in degree.

Sample
local yaw, pitch, roll = Image.Calibration.CameraModel.getEulerAngles(cameraModel)
getFocalDistance()
Short description

Get the camera model focus setting parameter.

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

focalDistance

FLOAT

Distance from the camera to the plane of best image sharpness.

unit

STRING

Focal distance unit. Default is mm.

Sample
local focalDistance, unit = Image.Calibration.CameraModel.getFocalDistance(cameraModel)
getIntrinsicK()
Short description

Get the intrinsic camera matrix.

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

intrinsic

OBJECT Matrix

A 3x3 matrix with the intrinsic camera parameters: K = [fx s cx, 0 fy cy, 0 0 1]

Sample
local intrinsic = Image.Calibration.CameraModel.getIntrinsicK(cameraModel)
getPosition()
Short description

Returns the position of the camera center as a 3D Point. If no extrinsic calibration is available the position will be in origin (0, 0, 0).

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

center

OBJECT Point

Camera center world position as a 3D point.

Sample
local center = Image.Calibration.CameraModel.getPosition(cameraModel)
getProjectionMatrix()
Short description

Get the 3x4 projection matrix P = K[R|t]. Transformation xp = K*(R*Xw + T), with xp = [u/z, v/z, z/z] = [x,y,1] in homogeneous coordinates and Xw = [X,Y,Z] in 3D world coordinates.

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

projectionMatrix

OBJECT Matrix

A 3x4 projection matrix P = K[R

Sample
local projectionMatrix = Image.Calibration.CameraModel.getProjectionMatrix(cameraModel)
getSensorToWorldDistortion()
Short description

Get the lens distortion coefficients [k1, k2, p1, p2, k3].

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

k1

FLOAT

Second order radial lens distortion coefficient.

k2

FLOAT

Fourth order radial lens distortion coefficient.

p1

FLOAT

First tangential lens distortion coefficient.

p2

FLOAT

Second tangential lens distortion coefficient.

k3

FLOAT

Sixth order radial lens distortion coefficient.

Sample
local k1, k2, p1, p2, k3 = Image.Calibration.CameraModel.getSensorToWorldDistortion(cameraModel)
getTransform()
Short description

Returns the pose of the camera as Transform object.

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

transform

OBJECT Transform

Rigid transformation from world to camera coordinates [R,t].

Sample
local transform = Image.Calibration.CameraModel.getTransform(cameraModel)
getWorldToSensorDistortion()
Short description

Get the lens distortion coefficients [k1, k2, p1, p2, k3].

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

k1

FLOAT

Second order radial lens distortion coefficient.

k2

FLOAT

Fourth order radial lens distortion coefficient.

p1

FLOAT

First tangential lens distortion coefficient.

p2

FLOAT

Second tangential lens distortion coefficient.

k3

FLOAT

Sixth order radial lens distortion coefficient.

Sample
local k1, k2, p1, p2, k3 = Image.Calibration.CameraModel.getWorldToSensorDistortion(cameraModel)
getXMLVersionTag()
Short description

Get the version tag of the XML file.

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

Return values
Name Type Description

versionTag

STRING

The version tag of the XML.

Sample
local versionTag = Image.Calibration.CameraModel.getXMLVersionTag(cameraModel)
load()
Short description

Load calibration result object from a file. This function is deprecated, please use Object.save/load instead.

See also

Object.load

Parameters
Name Type Description

fileName

STRING

Filename, including path and file extension.

Return values
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The calibration result object or nil

Sample
local cameraModel = Image.Calibration.CameraModel.load("private/CalibrationResult.xml)
save()
Short description

Save calibration result object to a file. This function is deprecated, please use Object.save/load instead.

See also

Object.save

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The instance to use.

fileName

STRING

Filename, including path and file extension.

Return values
Name Type Description

success

BOOL

Returns true if the file is written correctly.

Sample
local success = Image.Calibration.CameraModel.save(cameraModel, "private/CalibrationResult.xml")
setCalibrationImageSize()
Short description

Set the image size for which the calibration is valid.

Parameters
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The instance to use.

imageWidth

INT

The image width for which the calibration is valid.

imageHeight

INT

The image height for which the calibration is valid.

Sample
Image.Calibration.CameraModel.setCalibrationImageSize(cameraModel, imageWidth, imageHeight)
setCameraID()
Short description

Set the unique camera identifier.

Parameters
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The instance to use.

cameraID

STRING

The unique camera identifier.

Sample
Image.Calibration.CameraModel.setCameraID(cameraModel, cameraID)
setFocalDistance()
Short description

Set the camera model focus setting parameter.

Parameters
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The instance to use.

focalDistance

FLOAT

Distance from the camera to the plane of best image sharpness.

unit

STRING

Focal distance unit. Default is mm.

Sample
Image.Calibration.CameraModel.setFocalDistance(cameraModel, focalDistance, unit)
setIntrinsicK()
Short description

Set the intrinsic camera matrix.

Parameters
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The instance to use.

intrinsic

OBJECT Matrix

A 3x3 matrix with the intrinsic camera parameters: K = [fx s cx, 0 fy cy, 0 0 1]

Sample
Image.Calibration.CameraModel.setIntrinsicK(cameraModel, intrinsic)
setProjectionMatrix()
Short description

Set the 3x4 projection matrix P = K[R|t].

Parameters
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The instance to use.

projectionMatrix

OBJECT Matrix

A 3x4 projection matrix P = K[R

Sample
Image.Calibration.CameraModel.setProjectionMatrix(cameraModel, projectionMatrix)
setSensorToWorldDistortion()
Short description

Set the lens distortion coefficients [k1, k2, p1, p2, k3].

Parameters
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The instance to use.

k1

FLOAT

Set second order radial lens distortion coefficient.

k2

FLOAT

Set fourth order radial lens distortion coefficient.

p1

FLOAT

Set first tangential lens distortion coefficient.

p2

FLOAT

Set second tangential lens distortion coefficient.

k3

FLOAT

Set sixth order radial lens distortion coefficient.

Sample
local transform = Image.Calibration.CameraModel.setSensorToWorldDistortion(cameraModel, k1, k2, p1, p2, k3)
setTransform()
Short description

Set the pose transformation of the camera as Transform object.

Parameters
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The instance to use.

transform

OBJECT Transform

Rigid transformation describing the transformation from world to camera coordinates [R,t].

Sample
local transform = Image.Calibration.CameraModel.setTransform(cameraModel, transform)
setWorldToSensorDistortion()
Short description

Set the lens distortion coefficients [k1, k2, p1, p2, k3].

Parameters
Name Type Description

cameraModel

OBJECT Image.Calibration.CameraModel

The instance to use.

k1

FLOAT

Set second order radial lens distortion coefficient.

k2

FLOAT

Set fourth order radial lens distortion coefficient.

p1

FLOAT

Set first tangential lens distortion coefficient.

p2

FLOAT

Set second tangential lens distortion coefficient.

k3

FLOAT

Set sixth order radial lens distortion coefficient.

Sample
local transform = Image.Calibration.CameraModel.setWorldToSensorDistortion(cameraModel, k1, k2, p1, p2, k3)
toString()
Short description

Gets a short string description of the camera model.

Parameters
Name Type Description

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

The camera model object.

Return values
Name Type Description

str

STRING

Description of the camera model.

Sample
local str = Image.Calibration.CameraModel.toString(cameraModel)

Image.Calibration.Correction

Short description

Correction of image distortions based on a calibrated camera model. Supports correction of lens distortion and perspective distortion from small tilt angles and image rotations.

Keywords

distortion, lens, perspective, rectification, rectify, untilt, unwarp, undistort

See also

Functions

apply()
Short description

Apply the image correction to an input image.

Parameters
Name Type Description

corr

HANDLE

The correction object to use.

inputImage

CONST_OBJECT Image

Input image

Return values
Name Type Description

outputImage

OBJECT Image

Output image.

Sample
outputImage = corr:apply(inputImage)
create()
Short description

Create an image correction object.

Return values
Name Type Description

corr

HANDLE

Sample
corr = Image.Calibration.Correction.create()
getValidRegion()
Short description

Get a pixel region corresponding to the valid part of the corrected image. The valid part of the output image contains pixel values from the input image, and the invalid part is just set to zero.

Parameters
Name Type Description

corr

HANDLE

The correction object to use.

Return values
Name Type Description

validRegion

OBJECT Image.PixelRegion

Valid region of the output.

Sample
validRegion = corr:getValidRegion()
getVirtualCamera()
Short description

Get a camera model representing the virtual camera producing the corrected image.

Parameters
Name Type Description

corr

HANDLE

The correction object to use.

Return values
Name Type Description

camera

OBJECT Image.Calibration.CameraModel

Virtual camera of the correction procedure.

Sample
camera = corr:getVirtualCamera()
mapPoints()
Short description

Map points between the four coordinate systems related to the correction process. See the CoordinateSystem enum for details.

Parameters
Name Type Description

corr

HANDLE

The correction object to use.

pointsIn

OBJECT Point

Points to transform (single point or array).

sourceSystem

ENUM CoordinateSystem

Specifies the coordinate system in which the input point is defined.

targetSystem

ENUM CoordinateSystem

Specifies the coordinate system to transform the points into.

Return values
Name Type Description

pointsOut

OBJECT Point

Transformed points (single point or array).

Sample
pointsOut = corr:mapPoints(pointsIn, sourceSystem, targetSystem)
setAlignMode()
Short description

Setup the correction to map specific world ground plane rectangle to an image. This gives precise control of the pixel size and world origin of the output image.

Parameters
Name Type Description

corr

HANDLE

The correction object to setup.

cameraModel

OBJECT Image.Calibration.CameraModel

A model of a calibrated camera, as returned from the Image.Calibration functions.

worldRect

CONST_OBJECT Shape

World rectangle describing the world region to cover.

pixelSize

FLOAT

Desired pixel size (mm/pixel) of the output image. If omitted, a similar pixel size as in the input image center will be used.

interpolation

ENUM InterpolationMethod

Interpolation method to use. Default is LINEAR.

Sample
corr:setAlignMode(cameraModel, worldRect, pixelSize, interpolation)
setUndistortMode()
Short description

Setup the correction to compensate for lens distortion only. The other parts of the camera model are ignored.

Parameters
Name Type Description

corr

HANDLE

The correction object to setup.

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

A model of a calibrated camera, as returned from the Image.Calibration functions.

cropMode

ENUM CorrectionCropMode

Crop mode, determines how to crop the output. Default is FULL.

interpolation

ENUM InterpolationMethod

Interpolation method to use. Default is LINEAR.

Sample
corr:setUndistortMode(cameraModel, cropMode, interpolation)
setUntiltMode()
Short description

Setup the correction to compensate for lens distortion and perspective distortions caused by a tilt angle between the world ground plane and the camera. Any in-plane rotation between the camera and world is left unaltered.

Parameters
Name Type Description

corr

HANDLE

The correction object to setup.

cameraModel

CONST_OBJECT Image.Calibration.CameraModel

A model of a calibrated camera, as returned from the Image.Calibration functions.

cropMode

ENUM CorrectionCropMode

Crop mode, determines how to crop the output. Default is FULL.

interpolation

ENUM InterpolationMethod

Interpolation method to use. Default is LINEAR.

targetWidth

INT

Output image width. Default is same size as the input.

targetHeight

INT

Output image height. Default is same size as the input.

Sample
corr:setUntiltMode(cameraModel, pixelSize, origin)

Image.Fixture

Short description

Helper object for transformation of geometrical primitives between different views of the same object. This object is typically used in a locate-inspect concept, where a teach image is used to define a set of measurement tasks. These measurement tasks will then be executed on a set of live images, where the object to measure may be translated, rotated and/or scaled differently than in the teach image. Typically, the following steps are included in locate-inspect applications: - Teach a matching algorithm (EdgeMatcher, PointMatcher, PatternMatcher) from a teach image. Use the teach pose returned from the teach procedure as reference pose for the fixture. - Define a set of points or shapes in the teach image, related to various measurement tasks. Append these to the fixture using the append functions. - For each live image, find the object using a match call of the selected matching algorithm. Transform the fixture to this new object pose using Fixture.transform. - Get the transformed points or shapes using the get functions, now relating to the found pose of the object in the live image. Saving and loading a fixture: A Image.Fixture instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.

Keywords

local, object, reference, coordinate system

Functions

appendAngle()
Short description

Append an angle to the fixture.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the angle, used when retrieving the angle later on.

angle

FLOAT

Angle to append.

Sample
Image.Fixture.appendAngle(fixture, "angle1", 3.1415/2)
appendPoint()
Short description

Append a point to the fixture.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the point, used when retrieving the point later on.

point

CONST_OBJECT Point

Point to append.

Sample
Image.Fixture.appendPoint(fixture, "point1", point)
appendPose()
Short description

Append a pose transform to the fixture. Typically, the appended pose defines the pose of an object part. For example, the pose returned from the PatternVerifier teach method can be appended to a fixture. After calling Fixture.transform() to transform the fixture to a live image, Fixture.getPose() will give the pose of the part in the live image. The output from getPose can then be used in a call to PatternVerifier.verify() to verify the part in the live image.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the pose, used when retrieving the pose later on.

pose

CONST_OBJECT Transform

Pose to append, defined in image world coordinates.

Sample
Image.Fixture.appendPose(fixture, "pose1", pose)
appendShape()
Short description

Append a shape or composite shape to the fixture.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the shape, used when retrieving the shape later on.

shape

CONST_OBJECT Shape

Shape or composite shape to append.

Sample
Image.Fixture.appendShape(fixture, "shape1", shape)
create()
Short description

Create a new fixture.

Return values
Name Type Description

fixture

HANDLE

The new fixture.

Sample
fixture = Image.Fixture.create()
getAngle()
Short description

Get an angle from the fixture, transformed according to the current fixture transform.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the angle to retrieve.

Return values
Name Type Description

angle

FLOAT

The retrieved angle.

Sample
angle = Image.Fixture.getAngle(fixture, "angle1")
getAsPixelRegion()
Short description

Get a shape or composite shape region from the fixture, transformed directly to a pixel region for use as algorithm input. Since the returned object is not a shape, more general transformations are supported by this function compared to getShape().

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the shape or composite shape to retrieve.

referenceImage

CONST_OBJECT Image

Reference image, use to determine the pixel-world mapping.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

The transformed shape, converted to a pixel region.

Sample
region = Image.Fixture.getAsPixelRegion(fixture, "shape1", referenceImage)
getPoint()
Short description

Get a point from the fixture, transformed according to the current fixture transform.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the point to retrieve.

Return values
Name Type Description

point

OBJECT Point

The retrieved point.

Sample
point = Image.Fixture.getPoint(fixture, "point1")
getPose()
Short description

Get a pose from the fixture, transformed according to the current fixture transform. Typically, this is used to get the pose of an object part. For example, the pose returned from getPose can be used as input to the PatternVerifier match function. See appendPose for more information.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the pose to retrieve.

Return values
Name Type Description

pose

OBJECT Transform

The retrieved pose.

Sample
pose = Image.Fixture.getPose(fixture, "pose1")
getShape()
Short description

Get a shape or composite shape from the fixture, transformed according to the current fixture transform. Nil is returned if the shape can not be transformed accordingly.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the object to retrieve.

Return values
Name Type Description

shape

AUTO

The retrieved shape or composite shape.

Sample
shape = Image.Fixture.getShape(fixture, "shape1")
setReferencePose()
Short description

Set the reference pose of this fixture. This defines the object pose that all geometrical items will be related to. Typically, the teachPose output from the teach function of a matching tool (for example Image.Matching.EdgeMatcher.teach()) is used as input to this function.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

referencePose

CONST_OBJECT Transform

Pose transform of the object that all appended geometrical items will be related to.

Sample
Image.Fixture.setReferencePose(fixture, referencePose)
toString()
Short description

Get a user-friendly string description of the fixture.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

Return values
Name Type Description

description

STRING

User-friendly description of the fixture.

Sample
local description = Image.Fixture.toString(fixture)
transform()
Short description

Transform the fixture to a new pose. This will affect the pose of all geometrical items retrieved using the get functions. Typically, the pose transform output from the match function of a matching tool (for example Image.Matching.EdgeMatcher.match()) is often used as input to this function.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

poseTransform

CONST_OBJECT Transform

Pose transform of the new fixture pose.

Sample
Image.Fixture.transform(fixture, poseTransform)

Image.Fixture3D

Short description

Helper object for transformation of 3D geometrical primitives (Shapes, Points, regions). This object is typically used in a locate-inspect concept together with the EdgeMatcher3D, where a teach image is used to define a set of measurement tasks. These measurement tasks will then be executed on a set of live images, where the object to measure may be translated, rotated and/or scaled differently than in the teach image. The shadow region of a shape on the z=0 plane can be obtained directly using getAsPixelRegion. This function also allows more general transforms compared to the getShape function. E.g. using getPose on a circle will only allow up to similarity transforms, while getAsPixelRegion allows homography transforms. Typically, the following steps are included in locate-inspect applications: - Teach a 3D matching algorithm such as EdgeMatcher3D using a teach image. Use the teach pose returned from the teach procedure as reference pose for the fixture. - Define a set of points or shapes in the teach image, related to various measurement tasks. Append these to the fixture using the append functions. - For each live image, find the object using a match call of the selected matching algorithm. Transform the fixture to this new object pose using Fixture3D.transform(). - Get the transformed points or shapes using the get functions, now relating to the found pose of the object in the live image. Saving and loading a fixture: A Image.Fixture3D instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.

Keywords

local, object, reference, coordinate system

Functions

appendPoint()
Short description

Appends a 3D point to the fixture.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the point, used when retrieving the point later on.

point

CONST_OBJECT Point

3D point to append.

Sample
Image.Fixture3D.appendPoint(fixture, "point1", point)
appendPose()
Short description

Appends a pose transform (Transform 3D object) to the fixture. Typically, the appended pose defines the pose of an object part, for example, the pose returned from teaching 3D matchers for sub-components. After calling Fixture3D.transform() to transform the fixture to a live image, Fixture3D.getPose() will give the pose of the part in the live image.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the pose, used when retrieving the pose later on.

pose

CONST_OBJECT Transform

Transform pose (3D Transform) to append, defined in image world coordinates.

Sample
Image.Fixture3D.appendPose(fixture, "pose1", pose)
appendShape()
Short description

Appends a Shape3D object to the fixture.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the shape, used when retrieving the shape later on.

shape

CONST_OBJECT Shape3D

Shape3D object to append.

Sample
Image.Fixture3D.appendShape(fixture, "shape1", shape)
create()
Short description

Creates a new 3D fixture.

Return values
Name Type Description

fixture

HANDLE

The new fixture.

Sample
fixture = Image.Fixture3D.create()
getAsPixelRegion()
Short description

Gets a 3D shape from the fixture represented as a pixel region plus height boundaries (zMin, zMax). The pixel region is the convex hull of the shape projected onto the plane z = 0. More general transforms are allowed when using getAsPixelRegion, even transforms that changes the type of shape.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the shape to retrieve.

referenceImage

CONST_OBJECT Image

Reference image, used to supply the image world coordinate system.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

The transformed shape, converted to a pixel region.

zMin

FLOAT

The lowest z-value encountered in the shape after transformation but before projection.

zMax

FLOAT

The highest z-value encountered in the shape after transformation but before projection.

Sample
region = Image.Fixture3D.getAsPixelRegion(fixture, "shape1", referenceImage)
getPoint()
Short description

Gets a point from the fixture, transformed according to the current fixture transform.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the point to retrieve.

Return values
Name Type Description

point

OBJECT Point

The retrieved 3D point.

Sample
point = Image.Fixture3D.getPoint(fixture, "point1")
getPose()
Short description

Gets a pose from the fixture, transformed according to the current fixture transform. Typically, this is used to get the pose of an object part.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the pose to retrieve.

Return values
Name Type Description

pose

OBJECT Transform

The retrieved pose transform (Transform 3D).

Sample
pose = Image.Fixture3D.getPose(fixture, "pose1")
getShape()
Short description

Gets a shape from the fixture, transformed according to the current fixture transform.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

name

STRING

Name of the shape to retrieve.

Return values
Name Type Description

shape

OBJECT Shape3D

The retrieved 3D shape.

Sample
shape = Image.Fixture3D.getShape(fixture, "shape1")
setReferencePose()
Short description

Sets the reference pose of this fixture. This defines the object pose that all geometrical items will be related to. Typically, the teachPose output from the teach function of a matching tool, e.g., EdgeMatcher3D, is used as input to this function.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

referencePose

CONST_OBJECT Transform

Pose transform (Transform3D) of the object that all appended geometrical items will be related to.

Sample
Image.Fixture3D.setReferencePose(fixture, referencePose)
toString()
Short description

Gets a user-friendly string description of the fixture.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

Return values
Name Type Description

description

STRING

User-friendly description of the fixture.

Sample
local description = Image.Fixture3D.toString(fixture)
transform()
Short description

Transforms the fixture to a new pose. This will affect the pose of all geometrical items retrieved using the get functions. Typically, the pose transform output from the match function of a matching tool is often used as input to this function.

Parameters
Name Type Description

fixture

HANDLE

Fixture object.

poseTransform

CONST_OBJECT Transform

Pose transform (Transform 3D object) of the new fixture pose.

Sample
Image.Fixture3D.transform(fixture, poseTransform)

Image.Format

Short description

Image file formats/encodings.

Overview

Image.Format.BMP

Short description

BMP encoding functionality

Functions

create()
Short description

Creates a new instance of the BMP encoder.

Return values
Name Type Description

handle

HANDLE

Handle to the instance.

Sample
local handle = Image.Format.BMP.create()
decode()
Short description

Create an Image object from a binary buffer containing a BMP encoded image.

Parameters
Name Type Description

handle

HANDLE

Handle to the BMP instance

bmpBuffer

BINARY

Binary buffer containing the BMP encoded image

Return values
Name Type Description

image

OBJECT Image

Decoded image or nil

Sample
local image = Image.Format.BMP.decode(handle, bmpBuffer)
encode()
Short description

Create a binary buffer with the BMP encoded image data. Supported image types: UINT8, RGB24

Parameters
Name Type Description

handle

HANDLE

Handle to the instance

imageIn

CONST_OBJECT Image

image to encode

Return values
Name Type Description

bmpBuffer

BINARY

binary buffer containing the BMP encoded image or nil

Sample
local bmpBuffer = Image.Format.BMP.encode(handle, image)

Image.Format.JPEG

Short description

JPEG encoding functionality

Functions

create()
Short description

Creates a new instance of the JPEG encoder. Default quality level is 50.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance if available. Can be nil if unavailable.

Sample
local handle = Image.Format.JPEG.create()
decode()
Short description

Create an Image object from a binary buffer containing a JPEG encoded image.

Parameters
Name Type Description

handle

HANDLE

Handle to the JPEG instance

jpegBuffer

BINARY

Binary buffer containing the JPEG encoded image

Return values
Name Type Description

image

OBJECT Image

Decoded image or nil

Sample
local image = Image.Format.JPEG.decode(handle, jpegBuffer)
encode()
Short description

Create a binary buffer with the JPEG encoded image data.

Parameters
Name Type Description

handle

HANDLE

Handle to the JPEG instance

imageIn

CONST_OBJECT Image

Image to encode

Return values
Name Type Description

jpegBuffer

BINARY

Binary buffer containing the JPEG encoded image or nil

Sample
local jpegBuffer = Image.Format.JPEG.encode(handle, image)
setQuality()
Short description

Configure the JPEG encoding quality, a lower value results in higher compression.

Parameters
Name Type Description

handle

HANDLE

Handle to the JPEG instance

quality

INT

The minimum/maximum values depend on the underlying implementation.

Return values
Name Type Description

success

BOOL

True if successful, false otherwise

Sample
local success = Image.Format.JPEG.setQuality(handle, 50)

Image.Format.PNG

Short description

PNG encoding functionality

Functions

create()
Short description

Creates a new instance of the PNG encoder.

Return values
Name Type Description

handle

HANDLE

Handle to the instance.

Sample
local handle = Image.Format.PNG.create()
decode()
Short description

Create an Image object from a binary buffer containing a PNG encoded image.

Parameters
Name Type Description

handle

HANDLE

Handle to the PNG instance

pngBuffer

BINARY

Binary buffer containing the PNG encoded image

Return values
Name Type Description

image

OBJECT Image

Decoded image or nil

Sample
local image = Image.Format.PNG.decode(handle, pngBuffer)
encode()
Short description

Create a binary buffer with the PNG encoded image data. Supported image types: UINT8, UINT16, RGB24

Parameters
Name Type Description

handle

HANDLE

Handle to the instance

imageIn

CONST_OBJECT Image

image to encode

Return values
Name Type Description

pngBuffer

BINARY

binary buffer containing the PNG encoded image or nil

Sample
local pngBuffer = Image.Format.PNG.encode(handle, image)
setCompression()
Short description

Configure the PNG encoding compression (0-9), a higher value results in higher compression and higher run time.

Parameters
Name Type Description

handle

HANDLE

Handle to the PNG instance

compression

INT

Ranges from 0 (no compression) to 9 (high compression). Default: 6.

Return values
Name Type Description

success

BOOL

True if successful, false otherwise

Sample
local success = Image.Format.PNG.setCompression(handle, 1)

Image.Matching

Short description

Functions for matching and locating objects and patterns in images based on different object models, including edge-based models, interest point models and pixel pattern models.

Image.Matching.EdgeMatcher

Short description

Object matching of objects which are well defined by clean edges/contours in a 2D image. An alternative to the EdgeMatcher is the PointMatcher for objects whose appearance is rather described by a texture pattern. Teach an object model from a reference image and call match to find the location of the same object in a new image. The EdgeMatcher searches for translation, rotation and scale (range 80% - 120%) of objects. Results are given as pose transforms which describe how the object model is transformed to matched positions in the new image. Each match gets a score between 0.0 and 1.0 where 1.0 means a perfect match. The EdgeMatcher is often used together with the Image.Fixture object that facilitates local coordinate transforms based on the result of the EdgeMatcher. The most important parameters for the EdgeMatcher are the following: - Edge threshold: Make sure to select an edge strength threshold that includes the edges of the reference object but excludes clutter edges in the background. Use the getModelContours() function to graphically verify the object model obtained. - Background clutter: If the images contain other patterns and structures other than the object of interest, use the HIGH setting in setBackgroundClutter() which is the default. If the object is on a clean background one can gain speed by setting the background clutter flag to MEDIUM or LOW. There is an interaction with the background clutter setting and the downsample factor parameter below though: It can be possible to run with higher downsample factors using the HIGH background clutter and thus gain higher speed compared to runnning a MEDIUM background clutter and a lower downsample factor. - Downsample factor: The EdgeMatcher works internally on downsampled images for computational performance reasons. The downsample factor is the most important parameter for the speed versus robustness trade-off. A initial choice of downsample factor could be one that generates a downsampled image of size about 200 x 200. For example, if images of size 1024 x 1024 are used, one could start experimenting with a downsample factor of 5. The downsample factor has an effect on the robustness of the algorithm (finding the correct match) but not on the position accuracy. - Rotation range: The rotation range parameter should be selected to be as narrow as possible both for computational reasons and for robustness reasons. If it is known that the target object only can appear within a certain rotation interval relative to the teach pose, make sure to reduce the rotation range search parameter. - Scale range: As with the rotation range parameter, set the scale range as narrowly as possible for computational and performance reasons. Pixel types: The EdgeMatcher accepts uint8 and uint16 pixel type images. Hardware acceleration: Some devices have FPGA-support for the EdgeMatcher. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. If there is FPGA support it is set as default, but note that the FPGA is not able to support all configurations, mainly there is a lower restriction on the downsample factor for memory limitation reasons. There is typically only one instance of the FPGA calculation unit in a device. If many EdgeMatcher instances are created running in parallel, all using the FPGA acceleration, they may try to access the FPGA resource at the same time. The behavior is then that a match call will wait until the FPGA resource is available again. Image world coordinate system handling: The image (x,y)-pixelsize and origin are considered within the EdgeMatcher, all calculations are made in the image world coordinate system. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: The EdgeMatcher does not accept missing data images, turn off the missing data flag to use it anyway or use the EdgeMatcher3D. Object model: An object representation of the contours in the teach reference image is generated in a teach call. The center of the model, and also the rotation center, is the center of the teach region. Saving and loading a configuration: A trained EdgeMatcher instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.

Keywords

contour, find, matching, object, pattern, shape, locator

Functions

create()
Short description

Creates a new edge matcher for object localization in 2D intensity images.

Return values
Name Type Description

matcher

HANDLE

The new EdgeMatcher instance.

Sample
locator = Image.Matching.EdgeMatcher.create()
getDownsampleFactorLimits()
Short description

A support function which outputs the minimum and maximum values of the downsample factor. In particular when FPGA acceleration is utilized there are memory limitations setting a minimal value for the downsample factor. The maximum downsample factor is derived from the minimum allowed downsampled image size to look for matches in.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

image

CONST_OBJECT Image

An image with the size that the EdgeMatcher will work on

Return values
Name Type Description

minDsf

FLOAT

Minimum allowed downsample factor.

maxDsf

FLOAT

Maximum allowed downsample factor.

Sample
minDsf, maxDsf = Image.Matching.EdgeMatcher.getDownsampleFactorLimits(matcher, image)
getEdgePoints()
Short description

Deprecated: This function has been renamed to getModelPoints to align with the PointMatcher API. The functions give the same output. Get sample edges of the object represented as a vector of 2D Points. This function is intended for graphical feedback using representative points on edges of the reference object. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. Can only be called after a successful teach.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use.

Return values
Name Type Description

points

OBJECT Point

Edge points in internal model coordinates.

Sample
points = Image.Matching.EdgeMatcher.getEdgePoints(matcher)
getModelContours()
Short description

Get object model contours for visualization purposes. Results are returned as polyline shape objects.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use.

Return values
Name Type Description

polylines

OBJECT Shape

Edge lines in internal model coordinates.

Sample
polylines = Image.Matching.EdgeMatcher.getModelContours(matcher)
getModelPoints()
Short description

Get the object model as a vector of 2D Points of located edges. This function is intended for graphical feedback using representative points on edges of the reference object. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. Can only be called after a successful teach. Note: As it may be inefficient to overlay a lot of points in images, it is recommended to use the getModelContours function instead for graphical feedback.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use.

maxCount

INT

Optional parameter to specify the maximum number of control points along the polylines to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here.

Return values
Name Type Description

points

OBJECT Point

Edge points in internal model coordinates.

Sample
points = Image.Matching.EdgeMatcher.getModelPoints(matcher, 1000)
getTeachPose()
Short description

Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.

Parameters
Name Type Description

matcher

HANDLE

The instance to use

Return values
Name Type Description

teachPose

OBJECT Transform

2D pose transform transforming the object model to its position in the teach image, or nil if unsuccessful.

Sample
teachPose = Image.Matching.EdgeMatcher.getTeachPose(matcher)
match()
Short description

Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to the match in the live image. For the EdgeMatcher, the output posed transforms are of 2D Transform type. They can be used with the Fixture object to transform other 2D objects and regions. The match scores are based on how well edge information in the image matches the object model. The status code indicates what happened during the call and may be set to any of the following values: * 0: Matching was successful (although no objects may have been found, there was no error). * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 210: Timeout, matching was aborted. Check the set time limit. * 220: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 230: Region error, something was wrong with the search region. * 240: Unteached matcher, the matcher is not successfully teached. * 260: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use

liveImage

CONST_OBJECT Image

The live image to find the object in.

searchRegion

CONST_AUTO

Optional search region in the live image, either a pixel region or a closed 2D shape such as a rectangle. Edges are only detected within this region and it should cover the entire object to be found.

Return values
Name Type Description

poseTransforms

OBJECT Transform

Pose transforms defining the location of each detected object.

matchScores

FLOAT

A score between 0.0 and 1.0 for each detected object (high score means good match).

status

INT

A status code indicating what happened during the call.

Sample
transforms, scores, status = Image.Matching.EdgeMatcher.match(matcher, liveImage, searchRegion, priorRotation, priorScale)
setBackgroundClutter()
Short description

A setting that indicates to what level the live images supplied to the match function are expected to contain non-object edges. Keep this parameter at HIGH (default) if the image contains a lot of other edges, structures, noise, clutter in areas not belonging to the object of interest. Examples of such structures are barcodes and text which generate a lot of edge responses. For clean scenes this parameter can be set to MEDIUM or LOW to gain speed. Note however that it may be possible to work with higher downsample factors if this parameter is set to HIGH. Setting this parameter will invalidate any previous teach call.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

backgroundClutterLevel

AUTO

Set to the expected background clutter level, LOW, MEDIUM or HIGH. Default is HIGH. In a previous version of this function this input was a bool where 'true' maps to the MEDIUM enum and 'false' to the LOW enum.

Sample
Image.Matching.EdgeMatcher.setBackgroundClutter(matcher, backgroundClutterLevel)
setDownsampleFactor()
Short description

Sets downsampling factor in the x- and y-dimensions of the image. If the original image has size (M,N), the downsampled image has size (M/d, N/d) where d is the downsampling factor. More downsampling will increase the speed but eventually will reduce the matching robustness. Especially, for small object or thin contours the downsampling cannot be set too low as the details will become washed out in the downsampled image. However, some downsampling can also be beneficial for the matching as noise and irrelevant edges are removed. Therefore, a good downsampling is usually somewhere between 2.0 and 10.0. Setting a high downsampling does not have an impact on the final matching position accuracy as matches are fine-tuned on finer image resolutions. For FPGA acceleration there is lower limit on the downsampling factor due to memory limitations. This limit is different for various devices but is usually around 5.0 to 6.0. Use the getDownsampleFactorLimits to find out the lower and upper limits on the downsample factor.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

downsampleFactor

FLOAT

A factor larger than or equal to 1.0. The default value is 8.0.

Sample
Image.Matching.EdgeMatcher.setDownsampleFactor(matcher, 6.0)
setEdgeThreshold()
Short description

Sets the edge threshold, i.e., minimal edge strength. The edge strength is calculated as using a local image gradient filter so that smooth edges may generate weak edge responses. The default value is 50. For lower contrast edges one must reduce this value and for very sharp and high-contrast edges it should be raised. Check with the getModelContours() function the edges that are obtained. Setting this parameter will invalidate any previous teach call.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

threshold

FLOAT

Edge threshold. The default value is 50.

Sample
Image.Matching.EdgeMatcher.setEdgeThreshold(matcher, 20)
setMaxMatches()
Short description

Sets the maximum number of objects to find in a match call. Note that the actual number found can be smaller than this number. Increasing the number of matches to consider is also a way to control the number of match candidates considered within the algorithm. Thus, in cluttered scenes it may be possible to increase robustness to increase this parameter even if one knows that there is only one object present at the end. This parameter can be updated in a teached matcher without re-teaching.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

matchCount

INT

An integer larger than or equal to 1 specifying the maximum number of objects to find. The default value is 1.

Sample
Image.Matching.EdgeMatcher.setMaxMatches(matcher, 3)
setMinSeparation()
Short description

Sets the minimum separation between the centers of object matches. The unit is in image world units (typically millimeters) taking the image pixel size into account. For 2D images the pixel size is by default 1.0, in which case the value equals the separation in pixels. This parameter only has effect if the number of matches to find is larger than 1. This parameter can be updated in a teached matcher without re-teaching.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

minSeparation

FLOAT

The minimum separation between the centers of two objects in image world units. The default value is 50.

Sample
Image.Matching.EdgeMatcher.setMinSeparation(matcher, 100)
setProcessingUnit()
Short description

Sets processing unit for the calculations. Some devices support FPGA acceleration of the EdgeMatcher. If this is the case the FPGA acceleration is set as default when the EdgeMatcher object is created.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

processingUnit

ENUM EdgeMatcherProcessingUnit

Which type of processing unit to use. If there is FPGA support in the device it will be used as default, otherwise CPU.

Return values
Name Type Description

success

BOOL

True if processing unit choice was successfully set. False if the processing unit or configuration is not supported.

Sample
Image.Matching.EdgeMatcher.setProcessingUnit(matcher, "FPGA")
setRotationRange()
Short description

Sets rotation interval to search in relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. If prior orientation information is known, the prior rotation can be set to allow a more narrow search range. The final search range is then up to plus/minus the search range parameter starting from the prior rotation. These parameters can be updated in a teached matcher without re-teaching.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

rotationRad

FLOAT

Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI (180 degrees), i.e., full rotation.

priorRotationRad

FLOAT

Optional prior orientation in radians. If specified, the orientation search range is centered around this orientation. Default is zero (i.e. same orientation as teach object).

Sample
Image.Matching.EdgeMatcher.setRotationRange(matcher, rotationRad, priorRotationRad)
setScaleRange()
Short description

Sets scale interval to search relative to the teach size. The end points are represented as scale factors. setScaleRange(0.8, 1.2) searches for objects appearing down to 20% smaller or larger than the teach object. Default is not to search in scale, i.e, scale range parameters [1.0, 1.0]. An optional prior scale can be set, this affects both the minimum and maximum scale (both limits are multiplied with the prior scale). The prior scale moves the entire scale search range and does not affect matching time. The prior scale accepts a larger range of values than the min and max scale parameters. If the object to find has a fixed non-unit scale relative to the teach object, or if prior information on the scale of the object is available, use the prior scale. The default value is 1.0. By setting both minScale and maxScale to 1.0, scale search is disabled but the prior scale parameter still has effect. These parameters can be updated in a teached matcher without re-teaching.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

minScale

FLOAT

The smallest scale factor to search for. Lower limit is 0.8. Default value is 1.0.

maxScale

FLOAT

The largest scale factor to search for. Upper limit is 1.2. Default value is 1.0.

priorScale

FLOAT

Optional prior scale factor. Set to the expected scale of the object to find, relative to the size of the teach object. E.g. 1.25 if the object to find is 25% larger than the teach object. Min: 0.1. Max: 10

Sample
Image.Matching.EdgeMatcher.setScaleRange(matcher, minScale, maxScale, priorScale)
setTimeout()
Short description

Abort the match call if the match time exceeds a user-defined number of seconds. The main purpose is to protect against excessively long execution times, the granularity does not allow exact abortion at the given timeout parameter.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

timeoutSeconds

FLOAT

Time in seconds after which the algorithm should abort. The default value is 5 seconds.

Sample
Image.Matching.EdgeMatcher.setTimeout(matcher, 2.0)
teach()
Short description

Teaches an object model from edges in an image. It is important to set the edge strength threshold properly for this to work. Graphical feedback from the teach process is obtained through the getModelContours function. The status code indicates what happened during the call and may be set to any of the following values: * 0: Teaching was successful. * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 110: Timeout, teaching was aborted. Check the set time limit. * 120: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 130: Region error, something was wrong with the teach region. * 160: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy. * 170: Model edge error, too few model edges were found. Check the edge threshold, the input image and that the teach region covers the object of interest.

Parameters
Name Type Description

matcher

HANDLE

The instance to use

teachImage

CONST_OBJECT Image

The teach image.

teachRegion

CONST_AUTO

A pixel region or a closed 2D shape defining which area to consider as containing object edges.

Return values
Name Type Description

teachPoseTransform

OBJECT Transform

Pose transform of the object model, or nil if unsuccessful.

status

INT

A status code indicating what happened during the call.

Sample
teachPoseTransform, status = Image.Matching.EdgeMatcher.teach(matcher, teachImage, teachRegion)
toString()
Short description

Returns a human readable description of the matcher, including parameters.

Parameters
Name Type Description

matcher

HANDLE

The instance to use

Return values
Name Type Description

description

STRING

A description of the matcher object, or nil on failure.

Sample
description = Image.Matching.EdgeMatcher.toString(matcher)

Image.Matching.EdgeMatcher3D

Short description

The EdgeMatcher3D is an extension of the EdgeMatcher for object matching in range images and heightmaps. See the EdgeMatcher documentation for information on the basic usage. The documentation below focuses on the extensions and differences to the EdgeMatcher. The most important additional parameters and difference for the EdgeMatcher3D are the following: - The EdgeMatcher3D additionally searches for height and tilt (rotation around the x- and y-axes) of objects. The function setFindTiltHeight() enables and disables these additional parameters in the search. Tilt and height estimation is turned on as default. Turn these off for increased speed and robustness if the objects of interest always have the same tilt or height. - As range images generally contain missing data pixels, there is a mandatory "reference height" parameter that is set using the setReferenceHeight(). The EdgeMatcher3D uses this parameter to replace missing data pixels internally. - The output of the EdgeMatcher3D are 3D pose transforms. These can be used together with the Fixture3D object for locate-inspect applications. - Teach and search regions have additional zMin and zMax parameters to specify limits along the z-dimension. Pixel types: The EdgeMatcher3D accepts uint16 pixel type images. Hardware acceleration: Some devices have FPGA-support for the EdgeMatcher3D. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. If there is FPGA support it is set as default, but note that the FPGA is not able to support all configurations, mainly there is a lower restriction on the downsample factor for memory limitation reasons. There is typically only one instance of the FPGA calculation unit in a device. If many EdgeMatcher3D instances are created running in parallel, all using the FPGA acceleration, they may try to access the FPGA resource at the same time. The behavior is then that a match call will wait until the FPGA resource is available again. Image world coordinate system handling: All parameters (thresholds, zMin, zMax, reference height) use the z-origin and z-pixelsize. That is, the parameters are interpreted in world units, typically in millimeters. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: Both images with and without missing data flag are accepted. If the input image has missing data, the reference height parameter must be set to handle missing data internally. Object model: An object representation of the contours in the teach reference image is generated in a teach call. The center of the model, and also the rotation center, is the center of the teach region. The center in the z-dimension is (zMin + zMax)/2. Saving and loading a configuration: The configuration of a trained EdgeMatcher handle instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.

Functions

create()
Short description

Creates a new edge matcher for 3D object localization in range images.

Return values
Name Type Description

matcher

HANDLE

The new instance.

Sample
locator = Image.Matching.EdgeMatcher3D.create()
getDownsampleFactorLimits()
Short description

A support function which outputs the minimum and maximum values of the downsample factor. In particular when FPGA acceleration is utilized there are memory limitations setting a minimal value for the downsample factor. The maximum downsample factor is derived from the minimum allowed downsampled image size to look for matches in.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

image

CONST_OBJECT Image

An image with the size that the EdgeMatcher3D will work on.

Return values
Name Type Description

minDsf

FLOAT

Minimum allowed downsample factor.

maxDsf

FLOAT

Maximum allowed downsample factor.

Sample
minDsf, maxDsf = Image.Matching.EdgeMatcher3D.getDownsampleFactorLimits(matcher, image)
getModelContours()
Short description

Gets object model contours for visualization purposes. Results are returned as polyline Shape3D objects.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use.

Return values
Name Type Description

polylines

OBJECT Shape3D

Edge lines in internal model coordinates.

Sample
polylines = Image.Matching.EdgeMatcher3D.getModelContours(matcher)
getModelPlanePoints()
Short description

Gets object model points for visualization purposes. This function returns center points of planar patches.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use.

maxCount

INT

Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here.

Return values
Name Type Description

planarPoints

OBJECT Point

Vector of 3D planar points in internal model coordinates.

Sample
planarPoints = Image.Matching.EdgeMatcher3D.getModelPlanePoints(matcher)
getModelPoints()
Short description

Gets object model points for visualization purposes. This function returns points along the edges of object. See also getModelContours.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use.

maxCount

INT

Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here.

Return values
Name Type Description

points

OBJECT Point

Edge points in internal model coordinates.

Sample
points = Image.Matching.EdgeMatcher3D.getModelPoints(matcher)
getTeachPose()
Short description

Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.

Parameters
Name Type Description

matcher

HANDLE

The instance to use

Return values
Name Type Description

teachPose

OBJECT Transform

Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful.

Sample
teachPose = Image.Matching.EdgeMatcher3D.getTeachPose(matcher)
match()
Short description

Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to the match in the live image. For the EdgeMatcher3D, the output pose transforms are of 3D Transform type. They can be used with the Fixture3D object to transform other 3D objects and regions. The match scores are based on how well edge information in the image matches the object model. Currently, only (x,y) locations of edges are included in the score calculation, meaning that a mismatch in z-dimension can still give a high score. Image world coordinate system handling: The two parameters zMin and zMax specify the range interval of the teach region. The parameters are interpreted in image world units, typically millimeters, taking the z-origin and z-pixelsize of the input image into account. The status code indicates what happened during the call and may be set to any of the following values: * 0: Matching was successful (although no objects may have been found, there was no error). * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 210: Timeout, matching was aborted. Check the set time limit. * 220: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 230: Region error, something was wrong with the search region. * 240: Unteached matcher, the matcher is not successfully teached. * 250: Reference plane error, something was wrong with the reference height for missing data. * 260: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use

liveImage

CONST_OBJECT Image

The live image to find the object in.

searchRegion

CONST_AUTO

Optional search region in the live image, either a pixel region or a closed 2D shape such as a rectangle. Edges are only detected within this region and it should cover the entire object to be found.

zMin

FLOAT

Optional minimum value for z heights in world units (millimeters). Only edges above this level are included as features for the matching. If not set, a large negative number is used as default.

zMax

FLOAT

Optional maximum value for z heights in world units (millimeters). Only edges below this level are included as features for the matching. If not set, a large positive number is used as default.

Return values
Name Type Description

poseTransforms

OBJECT Transform

Pose transforms defining the location of each detected object.

matchScores

FLOAT

A score between 0.0 and 1.0 for each detected object (high score means good match).

status

INT

A status code indicating what happened during the call.

Sample
transforms, scores = Image.Matching.EdgeMatcher3D.match(matcher, liveImage)
proposeReferenceHeight()
Short description

Tries to estimate a reference height using valid pixels outside the teach region. Use this function carefully as it can give inaccurate results, for example if the teach region covers only the object partially.

Parameters
Name Type Description

matcher

HANDLE

The instance to use

teachImage

CONST_OBJECT Image

The teach image.

teachRegion

CONST_AUTO

A pixel region or a closed 2D shape defining which area to consider as containing object edges.

Return values
Name Type Description

referenceHeight

FLOAT

An estimated reference height in image world units, typically millimeters.. Returns nil if height estimation fails.

Sample
referenceHeight = Image.Matching.EdgeMatcher3D.proposeReferenceHeight(matcher, teachImage, teachRegion)
setBackgroundClutter()
Short description

A setting that indicates to what level the live images supplied to the match function are expected to contain non-object edges, e.g., noise and other clutter structures. The default setting is "MEDIUM". For very cluttered scenes it is possible to use a "HIGH" setting. Setting this parameter will invalidate any previous teach call.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

backgroundClutterLevel

AUTO

Set to the expected background clutter level, LOW, MEDIUM or HIGH. Default is MEDIUM.

Sample
Image.Matching.EdgeMatcher3D.setBackgroundClutter(matcher, backgroundClutterLevel)
setDownsampleFactor()
Short description

Sets downsample factor in the x- and y-dimensions of the image. If the original image has size (M,N), the downsampled image has size (M/d, N/d) where d is the downsample factor. More downsampling will increase the speed but eventually will reduce the matching robustness. Especially, for small object or thin contours the downsampling cannot be set too low as the details will become washed out in the downsampled image. However, some downsampling can also be beneficial for the matching as noise and irrelevant edges are removed. Therefore, a good downsampling is usually somewhere between 2.0 and 10.0. Setting a high downsampling does not have an impact on the final matching position accuracy as matches are fine-tuned on finer image resolutions.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

downsampleFactor

FLOAT

A factor larger than or equal to 1.0. The default value is 8.0.

Sample
Image.Matching.EdgeMatcher3D.setDownsampleFactor(matcher, downsampleFactor)
setEdgeThreshold()
Short description

Sets the edge threshold, i.e., minimal edge strength. The edge strength is calculated as using a local image gradient filter so that smooth edges may generate weak edge responses. The default value is 10. Check with the getModelPoints() or the getModelContours() function the edges that are obtained. Setting this parameter will invalidate any previous teach call. Image world coordinate system handling: The edge threshold is interpreted in the image world coordinate system, i.e., typically in millimeters. The threshold is converted internally to a raw pixel value threshold using the z-origin and z-pixelsize of the image.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

threshold

FLOAT

Edge threshold interpreted in the image world coordinate system. The default value is 10 for EdgeMatcher3D.

Sample
Image.Matching.EdgeMatcher3D.setEdgeThreshold(matcher, threshold)
setFindTiltHeight()
Short description

Flags to find the tilt and/or height of objects relative to the teach pose. Depending on the application, one may for example know that the tilt and or height is always the same as for the teach object. If so, turn off the estimation of these parameters for increased speed and robustness. If tilt-search is on, height-search is turned on automatically. Setting this parameter will invalidate any previous teach call. The maximum tilt angle the algorithm can find is about 10 - 15 degrees relative to the teach pose, for higher tilts the algorithm may not match robustly.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use.

findTilt

BOOL

Set to true to find tilt of matched objects. Default is true.

findHeight

BOOL

Set to true to find height of matched objects. Default is true.

Sample
Image.Matching.setFindTiltHeight(matcher, findTilt, findHeight)
setMaxMatches()
Short description

Sets the maximum number of objects to find in a match call. Note that the actual number found can be smaller than this number. This parameter can be updated in a teached matcher without re-teaching.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

matchCount

INT

An integer larger than or equal to 1 specifying the maximum number of objects to find. The default value is 1.

Sample
Image.Matching.EdgeMatcher3D.setMaxMatches(matcher, matchCount)
setMinSeparation()
Short description

Sets the minimum separation in the (x,y)-dimension between the centers of object matches. This parameter only has effect if the number of matches to find is larger than 1. This parameter can be updated in a teached matcher without re-teaching. Image world coordinate system handling: The unit is in image world units (typically millimeters) taking the image (x,y)-pixelsizes into account.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

minSeparation

FLOAT

The minimum separation between the centers of two objects in image world units. The default value is 50.

Sample
Image.Matching.EdgeMatcher3D.setMinSeparation(matcher, minSeparation)
setProcessingUnit()
Short description

Sets processing unit for the calculations. Some devices support FPGA acceleration of the EdgeMatcher3D. If this is the case the FPGA acceleration is set as default when the EdgeMatcher3D object is created.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

processingUnit

ENUM EdgeMatcherProcessingUnit

Which type of processing unit to use. If there is FPGA support in the device it will be used as default, otherwise CPU.

Return values
Name Type Description

success

BOOL

True if processing unit choice was successfully set. False if the chosen processing unit is not supported.

Sample
Image.Matching.EdgeMatcher3D.setProcessingUnit(matcher, "FPGA")
setReferenceHeight()
Short description

Sets a reference height for missing data handling. This value is used to replace missing data pixels within the algorithm. Use the height of the floor, belt or any other application-dependent height. Setting this parameter is mandatory if the input images have the missing data flag on. If missing data has been removed before calling the EdgeMatcher3D, this parameter has no effect. This parameter can be updated in a teached matcher without re-teaching. A suggested reference height can be obtained using the proposeReferenceHeight()-function. Image world coordinate system handling: The reference height is interpreted in the image world coordinate system, typically in millimeters, considering the z-origin and z-pixelsize of the image.

Parameters
Name Type Description

matcher

HANDLE

The matcher instance to use.

referenceHeight

FLOAT

Reference height specified in world units, e.g., millimeters.

Sample
Image.Matching.EdgeMatcher3D.setReferenceHeight(matcher, referenceHeight)
setRotationRange()
Short description

Sets rotation interval around the z-axis to search in relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. This parameter can be updated in a teached matcher without re-teaching.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

rotationRad

FLOAT

Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI.

Sample
Image.Matching.EdgeMatcher3D.setRotationRange(matcher, rotationRad)
setTimeout()
Short description

Abort the match call if the match time exceeds a user-defined number of seconds. The main purpose is to protect against excessively long execution times, the granularity does not allow exact abortion at the given timeout parameter.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

timeoutSeconds

FLOAT

Time in seconds after which the algorithm should abort. The default value is 5 seconds.

Sample
Image.Matching.EdgeMatcher3D.setTimeout(matcher, timeoutSeconds)
teach()
Short description

Teaches an object model from edges in an image. It is important to set the edge strength threshold properly for this to work. Graphical feedback from the teach process is obtained through the getModelPoints() or getModelContours() functions. The teach procedure extracts both edge information and planar patches within the teach region. The latter are used to estimate tilt and height parameters in match. Image world coordinate system handling: The two parameters zMin and zMax specify the range interval of the teach region. The parameters are interpreted in image world units, typically millimeters, taking the z-origin and z-pixelsize of the input image into account. The status code indicates what happened during the call and may be set to any of the following values: * 0: Teaching was successful. * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 110: Timeout, teaching was aborted. Check the set time limit. * 120: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 130: Region error, something was wrong with the teach region. * 150: Reference plane error, something was wrong with the reference height for missing data. * 160: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy. * 170: Model edge error, too few model edges were found. Check the edge threshold, the input image and that the teach region covers the object of interest. * 180: Model plane error, too few planar probes were found. See status code 170.

Parameters
Name Type Description

matcher

HANDLE

The instance to use

teachImage

CONST_OBJECT Image

The teach image.

teachRegion

CONST_AUTO

A pixel region or a closed 2D shape defining which area to consider as containing object edges.

zMin

FLOAT

Optional minimum value for z heights in world units (millimeters). Only edges and planar points above this level are included in the model. If not set, a large negative number is used as default.

zMax

FLOAT

Optional maximum value for z heights in world units (millimeters). Only edges and planar points below this level are included in the model. If not set, a large positive number is used as default.

Return values
Name Type Description

teachPoseTransform

OBJECT Transform

Pose transform of the object model, or nil if unsuccessful.

status

INT

A status code indicating what happened during the call.

Sample
teachPoseTransform, status = Image.Matching.EdgeMatcher3D.teach(matcher, teachImage, teachRegion)
toString()
Short description

Returns a human readable description of the matcher, including parameters.

Parameters
Name Type Description

matcher

HANDLE

The instance to use

Return values
Name Type Description

description

STRING

A description of the matcher object.

Sample
description = Image.Matching.EdgeMatcher3D.toString(matcher)

Image.Matching.PatternMatcher

Short description

Finds an object in an image based on its pixel pattern. Teach the object from a reference image and call match to find the location of the same object in a live image. The PatternMatcher primarily searches for translated and rotated objects. Search in scale can be activated. Results are given in pose transforms which describe how the object model is transformed to matched positions in the live image. Each match gets a score between 0.0 and 1.0 where 1.0 means a perfect match. The PatternMatcher is often used together with the Fixture object that facilitates local coordinate transforms based on the result of the PatternMatcher. The most important parameters for the PatternMatcher are the following: - Downsample factor: The PatternMatcher works internally on downsampled images for computational performance reasons. The downsample factor is the most important parameter for the speed versus robustness trade-off. A initial choice of downsample factor could be one that generates a downsampled image of size about 150 x 150. That is, if images of size 1024 x 1024 are used, one could start experimenting with a downsample factor of around 7. A warning will be issued during teach if the downsample factor makes the object model too small. - Rotation range: The rotation range parameter should be selected to be as narrow as possible both for computational reasons and for robustness reasons. If it is known that the target object only can appear within a certain rotation interval, make sure to reduce the rotation range search parameter.

Keywords

correlation, matching, pixel, template, locator

Functions

create()
Short description

Creates a new pattern matcher for 2D object localization.

Return values
Name Type Description

locator

HANDLE

The new instance.

Sample
locator = Image.Matching.PatternMatcher.create()
getDownsampleFactor()
Short description

Gets the current downsample parameter setting.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

Return values
Name Type Description

downsampleFactor

FLOAT

The current downsample factor.

Sample
downsampleFactor = Image.Matching.PatternMatcher.getDownsampleFactor(locator)
getMaxMatches()
Short description

Gets the current maximum number of objects to find.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

Return values
Name Type Description

matchCount

INT

The current maximum number of objects to find.

Sample
matchCount = Image.Matching.PatternMatcher.getMaxMatches(locator)
getMinSeparation()
Short description

Gets the current minimum separation between centers of object matches.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

Return values
Name Type Description

minSeparation

FLOAT

The minimum separation between the centers of two objects in image world units.

Sample
minSeparation = Image.Matching.PatternMatcher.getMinSeparation(locator)
getModelBoundingBox()
Short description

Get a bounding box of the teach object centered on the image world origin. It can be transformed directly by the pose transformations obtained from match to visualize matching results.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

Return values
Name Type Description

modelBox

OBJECT Shape

A rectangle Shape representing the bounding box of the teach region, or nil if unsuccessful.

Sample
modelBox = Image.Matching.PatternMatcher.getModelBoundingBox(locator)
getRotationRange()
Short description

Gets the current rotation range parameter.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

Return values
Name Type Description

rotationRad

FLOAT

The current rotation range.

Sample
rotationRad = Image.Matching.PatternMatcher.getRotationRange(locator)
getTeachPose()
Short description

Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

Return values
Name Type Description

teachPose

OBJECT Transform

Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful.

Sample
teachPose = Image.Matching.PatternMatcher.getTeachPose(matcher)
getTimeout()
Short description

Gets the selected timeout for matching.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

Return values
Name Type Description

timeoutSeconds

FLOAT

Time in seconds after which the algorithm will abort.

Sample
timeoutSeconds = Image.Matching.PatternMatcher.getTimeout(locator)
match()
Short description

Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to matched positions in the live image.

Parameters
Name Type Description

locator

HANDLE

The matcher instance to use.

liveImage

CONST_OBJECT Image

The live image to find the object in.

searchRegion

CONST_OBJECT Shape

Optional search region in the live image, must be a rectangle.

Return values
Name Type Description

poseTransforms

OBJECT Transform

Pose transforms defining the location of each detected object.

matchScores

FLOAT

A score between 0.0 and 1.0 for each detected object (high score means good match).

Sample
transforms, scores = Image.Matching.PatternMatcher.match(locator, liveImage)
setDownsampleFactor()
Short description

Sets the downsample factor. Increasing this value will reduce computation time, but also reduce accuracy.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

downsampleFactor

FLOAT

A factor larger than or equal to 1.0. The default value is 16.

Sample
Image.Matching.PatternMatcher.setDownsampleFactor(locator, 10.0)
setEdgeSensitivity()
Short description

Sets sensitivity to edge pixel intensity values used when matching. Sharp edges generate large errors for noisy edge positions, setting a low sensitivity (default) reduces errors due to small edge position variations among objects and typically increases the performance of the matcher.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

edgeSensitivity

ENUM EdgeSensitivity

Sensitivity to edge pixels (e.g.: LOW, HIGH).

Sample
Image.Matching.PatternMatcher.setEdgeSensitivity(locator, edgeSensitivity)
setMaxMatches()
Short description

Sets the maximum number of objects to find in a match call. The actual number of matches found can be smaller than this number. This parameter can be changed without re-teaching.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

matchCount

INT

An integer larger or equal than 1 specifying the maximum number of object to find.

Sample
Image.Matching.PatternMatcher.setMaxMatches(locator, 3)
setMinSeparation()
Short description

Sets the minimum separation between the centers of object matches. The unit is in image world units (typically millimeters) taking the image pixel size into account. For 2D images the pixel size is by default 1.0, in which case the value equals the separation in pixels. This parameter can be changed without re-teaching.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

minSeparation

FLOAT

The minimum separation between the centers of two objects in image world units. The default value is 50.

Sample
Image.Matching.PatternMatcher.setMinSeparation(locator, 50)
setRotationRange()
Short description

Sets the rotation interval to search in, relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

rotationRad

FLOAT

Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI/16.

Sample
Image.Matching.PatternMatcher.setRotationRange(locator, 3.1415/16)
setScaleSearch()
Short description

Activates searching for objects of different scales, from minimalSize to maximalSize. By default, no scale search is active, corresponding to setScaleSearch(1.0, 1.0).

Parameters
Name Type Description

locator

HANDLE

The instance to use

minimalScale

FLOAT

Size of objects relative to teach object, 0.5 searches for objects down to half the size of the teach object.

maximalScale

FLOAT

Size of objects relative to teach object, 2.0 searches for objects up to double the size of the teach object.

Sample
Image.Matching.PatternMatcher.setScaleSearch(locator, minimalScale, maximalScale)
setTimeout()
Short description

Abort the match call if the match time exceeds a user-defined number of seconds. The default value is 5 seconds. This parameter can be changed without re-teaching.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

timeoutSeconds

FLOAT

Time in seconds after which the algorithm should abort.

Sample
Image.Matching.PatternMatcher.setTimeout(locator, 10.0)
teach()
Short description

Teaches an object model from an image. It is important to set a reasonable downsample factor and the desired rotational range beforehand.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

teachImage

CONST_OBJECT Image

The teach image.

teachRegion

CONST_AUTO

A pixel region or closed 2D shape defining which area to consider as containing the object.

Return values
Name Type Description

teachPoseTransform

OBJECT Transform

Pose transform of the object model, or nil if unsuccessful.

Sample
teachPose = Image.Matching.PatternMatcher.teach(locator, teachImage, teachRegion)
toString()
Short description

Returns a human readable description of the matcher, including parameters.

Parameters
Name Type Description

handle

HANDLE

The matcher instance to use.

Return values
Name Type Description

description

STRING

A description of the matcher object, or nil on failure.

Sample
description = Image.Matching.PatternMatcher.toString(handle)

Image.Matching.PatternVerifier

Short description

Verifies a pixel value pattern. Create a new instance using the create function, set parameters using the set functions, teach the correct pattern from a reference image and call verify to find the similarity to the taught pattern. The PatternVerifier can tolerate some errors in the given translation, rotation and scale of the pattern to verify, however for large uncertainties, use a matcher object to find the pattern first. By default all tolerances are set to zero. Results are given as similarity scores as well as an image indicating where the differences are. A refined pose is returned.

Keywords

checking, comparison, pixel, verification, correlation

Functions

create()
Short description

Creates a new pattern verifier for pixel value pattern verification.

Return values
Name Type Description

verifier

HANDLE

The new instance.

Sample
verifier = Image.Matching.PatternVerifier.create()
generateOverlay()
Short description

Generates an overlay PixelRegion by thresholding a difference image. The overlay is transformed to match the latest live image and refined pose.

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

differenceImage

CONST_OBJECT Image

Difference image to threshold.

threshold

FLOAT

Threshold for difference image, all pixels with values above the threshold will be included in the pixel region.

Return values
Name Type Description

overlay

OBJECT Image.PixelRegion

Overlay pixel region, or nil if unsuccessful.

Sample
overlay = Image.Matching.PatternVerifier.generateOverlay(verifier, differenceImage, threshold)
getModelBoundingBox()
Short description

Get a bounding box of the teach object centered on the image world origin. It can be transformed directly by the pose transformations sent to and obtained from verify to visualize the working area of the verifier.

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

Return values
Name Type Description

modelBox

OBJECT Shape

A rectangle Shape representing the bounding box of the teach region, or nil if unsuccessful.

Sample
modelBox = Image.Matching.PatternVerifier.getModelBoundingBox(verifier)
setEdgeSensitivity()
Short description

Sets the sensitivity to edge pixel intensity values used when verifying. Sharp edges generate large errors for noisy edge positions, setting a low sensitivity (default) reduces errors due to small edge position variations among objects.

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

edgeSensitivity

ENUM EdgeSensitivity

Sensitivity to edge pixels (e.g.: HIGH, LOW).

Sample
Image.Matching.PatternVerifier.setEdgeSensitivity(verifier, edgeSensitivity)
setPositionTolerance()
Short description

Sets how much the position of the pattern may deviate from the pose given to the verify function. Narrowing the translational search range speeds up the verification considerably. The range is given as a distance in world units, allowing the pattern to be translated up to plus/minus the distance along both dimensions.

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

translation

FLOAT

Allowed distance in world units. The default tolerance is zero.

Sample
Image.Matching.PatternVerifier.setPositionTolerance(verifier, 2.0)
setRotationTolerance()
Short description

Sets how much the rotation of the pattern may deviate from the pose given to the verify function. Narrowing the rotation search range speeds up the verification considerably. The range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle.

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

rotationRad

FLOAT

Angle in radian units, the maximum deviation from the given object orientation to search for. The default tolerance is zero.

Sample
Image.Matching.PatternVerifier.setRotationTolerance(verifier, 3.1415/16)
setScaleTolerance()
Short description

Sets how much the scale of the pattern may deviate from the pose given to the verify function. Narrowing the scale search range speeds up the verification considerably. The range is given as the minimum and maximum size of the pattern, relative to the transformation supplied to the verify function. The default is no scale change tolerance, i.e., setScaleTolerance(1.0, 1.0).

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

minimumScale

FLOAT

Minimum relative scale to accept, e.g. setting to 0.9 allows pattern sizes down to 90%.

maximumScale

FLOAT

Maximum relative scale to accept, e.g. setting to 1.1 allows pattern sizes up to 110%.

Sample
Image.Matching.PatternVerifier.setScaleTolerance(verifier, 0.9, 1.1)
setTimeout()
Short description

Abort the verify call if the verify time exceeds a user-defined number of seconds. The default value is 5 seconds.

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

timeoutSeconds

FLOAT

Time in seconds after which the algorithm should abort.

Sample
Image.Matching.PatternVerifier.setTimeout(verifier, 2.0)
teach()
Short description

Teaches a pattern from an image. The returned pose is usually appended to a Fixture related to the main inspected object.

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

teachImage

CONST_OBJECT Image

The teach image.

teachRegion

CONST_OBJECT Image.PixelRegion

A pixel region defining which area to consider as containing the pattern.

Return values
Name Type Description

teachPoseTransform

OBJECT Transform

Pose transform of the pattern, or nil if unsuccessful.

Sample
teachPose = Image.Matching.PatternVerifier.teach(verifier, teachImage, teachRegion)
toString()
Short description

Returns a human readable description of the pattern verifier, including parameters.

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

Return values
Name Type Description

description

STRING

A description of the verifier, or nil on failure.

Sample
description = Image.Matching.PatternVerifier.toString(verifier)
verify()
Short description

Verifies a pattern by comparing to the teach pattern. A teach call must be made first. Some errors in the pose can be tolerated by setting the respective tolerance values.

Parameters
Name Type Description

verifier

HANDLE

The instance to use.

liveImage

CONST_OBJECT Image

The live image to verify the pattern in.

pose

CONST_OBJECT Transform

The pose of the pattern to be verified, usually obtained from a Fixture.

Return values
Name Type Description

score

FLOAT

A score between 0.0 and 1.0, or nil if unsuccessful. High score means the pattern is similar to the teach pattern.

differenceImage

OBJECT Image

The difference image, indicating where the patterns differ, or nil if unsuccessful. Pixel values close to zero indicate areas where the patterns match. The default image contains the absolute pixel value differences between the live image and the transformed teach pattern. The difference image is sampled in an object-centered coordinate system with the origin in the center of the image, and cropped to the bounding box of the teach pattern. Any indications in the difference image should be transformed using the refinedPose to obtain the corresponding position in the live image.

refinedPose

OBJECT Transform

The refined pose of the pattern, or nil if unsuccessful. If all tolerances are set to zero, this will be equal to the given pose.

Sample
score, differenceImage, refinedPose = Image.Matching.PatternVerifier.verify(verifier, liveImage, pose)

Image.Matching.PointMatcher

Short description

Finds an object in an image based on feature points. Salient points are found on the reference object and similar points are searched for in the live images. Teach the object from a reference image and call match to find the location of the same object in a live image. The strength of the PointMatcher relative the EdgeMatcher is for objects whose appearance can be described in terms of textured pattern rather than clear edges or contours. The PointMatcher can also easily find large scale or perspective changes which the EdgeMatcher cannot. The outputs from the PointMatcher are a so-called pose transform and a match score. The pose transform is a Transform object which transforms the model points extracted in the teach step to the matched location in the live image. The PointMatcher is often used together with the Fixture object that facilitates local coordinate transforms based on the pose transform. The match score is a number between 0.0 and 1.0 indicating the fraction of model points that have a match in the input image. The most important parameters for the PointMatcher are the following: - Pose type: This parameter tells the PointMatcher which type of appearance change to look for in the match process, e.g., does the object of interest change size relative to the teach object, does the camera position change leading to a perspective change of the imaged object, etc.? Restrict the pose type as much as possible for a more robust matching. By default, the pose type is restricted and must explicitly be set to allow more general pose transforms. See the documentation of the setPoseType-function for more information. - Pose variability: If the object of interest is imaged from very different angles or distances, leading to large perspective or scale changes, set the pose variability to HIGH for more robustness. Otherwise, set the pose variability to LOW for a higher matching speed. Use the setPoseVariability-function to set the pose variability. - Point count: The target number of salient points to extract. Fewer points will make the matching faster, but with too few points the matching will fail. Use setPointCount() to reduce the number of points. - Downsample factor: Tells the PointMatcher to work on a downsampled version of the input image. This can increase speed and in some cases even robustness if the original image is of high-resolution. Setting the downsample factor too high reduces the robustness though as the feature points in the ensuing low resolution image are not distinct enough. - Rotation range: The rotation range narrows the expected rotations relative to the teach pose. This parameter does not affect matching speed but increases robustness as false matches can be rejected. Set this range as narrow as possible but still wide enough to let valid matches through. - Scale range: The scale range narrows the expected scale change to the teach pose. This parameter does not affect matching speed but increases robustness as false matches can be rejected. Set this range as narrow as possible but still wide enough to let valid matches through. Restrictions: - Only uint8 images are accepted. - The PointMatcher can currently only find 1 object instance per image. Image world coordinate system handling: The image (x,y)-pixelsize and origin are considered, all calculations are made in the image world coordinate system. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: The PointMatcher does not accept missing data images, remove missing data first before usage.

Keywords

descriptor, feature point, interest point, keypoint, landmark, matching, object, perspective, locator

Functions

create()
Short description

Creates a new point matcher for 2D object localization.

Return values
Name Type Description

locator

HANDLE

The new instance.

Sample
locator = Image.Matching.PointMatcher.create()
getDetectedPoints()
Short description

Fetches two lists with salient points that were detected in the live image during the last match call. Points are returned in world coordinates and are intended to be plotted directly on the live image for graphical feedback. The first list contains all detected points while the second list only contains those points that were matched and found to be geometrically consistent with the corresponding model point under the found pose transformation.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

Return values
Name Type Description

detectedPointsWorld

OBJECT Point

Detected salient points during the last call to match, may be empty.

matchedPointsWorld

OBJECT Point

Matched points in the last live image, in world coordinates. The matched points are a subset of the detected salient points.

Sample
detectedPointsWorld, matchedPointsWorld = Image.Matching.PointMatcher.getDetectedPoints(locator)
getModelPoints()
Short description

Gets the list of salient points detected during the last teach call as a vector of 2D Points. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. A maximum number of points to return may be specified. The default is to return all points. This function is intended for graphical feedback. Note: to control the number of points detected in the image and used when matching, use the setPointCount function.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

maxCount

INT

Optional parameter to specify the maximum number of points to return. Default is to return all points. Note that one can obtain fewer points than the value specified here.

Return values
Name Type Description

points

OBJECT Point

Salient model points in internal model coordinates, may be empty.

Sample
points = Image.Matching.PointMatcher.getModelPoints(locator, maxCount)
getTeachPose()
Short description

Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.

Parameters
Name Type Description

matcher

HANDLE

The instance to use

Return values
Name Type Description

teachPose

OBJECT Transform

Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful.

Sample
teachPose = Image.Matching.PointMatcher.getTeachPose(matcher)
match()
Short description

Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms with one or zero entries, or nil. An empty vector indicates that no object was found while nil indicates that the matcher encountered an error. The transform describes how the object model is transformed to matched positions in the live image. The optional search region indicates where salient points will be extracted and should include the entire area where the object may appear. By default, the entire image is used. Use getDetectedPoints after match to visualize detected salient points in the live image and salient points matched to the model.

Parameters
Name Type Description

locator

HANDLE

The matcher instance to use.

liveImage

CONST_OBJECT Image

The live image to find the object in.

searchRegion

CONST_OBJECT Shape

Optional search region in the live image, must be a rectangle.

Return values
Name Type Description

poseTransforms

OBJECT Transform

Pose transform defining the location of any detected object. Note that this is a vector with at most one element/transform for future compatibility when adding multiple matches.

matchScores

FLOAT

A score between 0.0 and 1.0 for any detected object (high score means good match). Note that this is a vector with at most one element/score for future compatibility when adding multiple matches.

inlierRMS

FLOAT

The root mean squared error among inlier points in world coordinates (lower is better). Note that this is a vector with at most one element/value for future compatibility when adding multiple matches.

Sample
poseTransforms, matchScores, inlierRMS = Image.Matching.PointMatcher.match(locator, liveImage)
setDownsampleFactor()
Short description

Sets the factor in the x- and y-dimensions for the internal downsampling of the image. Increasing this value will reduce the time required for detecting salient points. A larger downsampling factor may improve results in cases where the image structure is smooth or slightly out of focus. A higher downsampling factor reduces the accuracy of the estimated pose.

Parameters
Name Type Description

matcher

HANDLE

The instance to use. Default is 2.0.

downsampleFactor

FLOAT

A factor larger than or equal to 1.0.

Sample
Image.Matching.PointMatcher.setDownsampleFactor(matcher, downsampleFactor)
setIterations()
Short description

Sets the maximum number of iterations in the geometrical robust fitting step. Decreasing this parameter makes the geometrical matching faster, however using too small values, good matches may be missed. When a match with high probability of being the correct one is found, fewer iterations may be used. The number of iterations set here is also used to control the probability threshold, where a higher number of iterations corresponds to requiring a higher probability of a correct match before stopping the iteration in advance.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

iterations

INT

Number of iterations, must be larger than one, the default is 5000.

Sample
Image.Matching.PointMatcher.setIterations(locator, iterations)
setOutlierMargin()
Short description

Set the outlier margin in world units, must be greater than zero. The point matcher searches for the transform that is supported by the highest number of salient points. This setting determines how far a transformed model point can be from the corresponding live image point before it is considered an outlier and not supporting the current transform hypothesis. Decreasing this parameter will require the salient points of the template and live images to be geometrically more coherent. A too small value will remove almost all point match candidates, which will reduce object match accuracy significantly.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

margin

FLOAT

Outlier margin in world units, the default is 5.0.

Sample
Image.Matching.PointMatcher.setOutlierMargin(locator, margin)
setPointCount()
Short description

Sets the desired number of salient points to detect in an image. The final number of points may be larger or smaller. The desired number of points is related to the full image. For a part of an image, the number of found points is lower in general.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

desiredPointCount

INT

A larger number generates more keypoints, default 1000.

Sample
Image.Matching.PointMatcher.setPointCount(locator, desiredPointCount)
setPoseType()
Short description

The pose type puts a limit on the generality of pose transforms returned by the match function. In the following list, the first option is the most restrictive and every new type contains all previously listed types as special cases. "RIGID" - Searches for objects whose image appears translated and rotated. The scale range is ignored in this mode. Set rotation range to zero for pure translations. "SIMILARITY" - Searches for objects whose image appears translated, rotated and uniformly scaled. This is the default option. Set rotation range to zero for translation and scaling only. "AFFINE" - Searches for objects whose image appears translated, rotated, non-uniformly scaled and skewed. "HOMOGRAPHY" - This is the most general transform, it allows e.g. out-of-plane rotation for flat objects.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

poseTransformType

ENUM Image.Matching.PointMatcher.PoseType

The type of pose transformation to allow when searching for matching objects.

Sample
Image.Matching.PointMatcher.setPoseType(locator, poseTransformType)
setPoseVariability()
Short description

Set to the expected variability in pose of the objects in the live image. Setting a higher variability will use more robust salient point detectors and descriptors but those will be slower in most cases. In general, try the lowest setting first and change to higher settings if required. "HIGH" - The default value, more robust but also slower in general. "LOW" - Faster in general and should be fine for any rotation, scale changes up to at least 30% and small perspective effects. When using this mode, the image size in pixels must be the same for all images.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

variability

ENUM PoseVariability

The expected pose variability of objects in the live image.

Sample
Image.Matching.PointMatcher.setPoseVariability(locator, variability)
setRotationRange()
Short description

Sets rotation interval to search within, in relation to the teach orientation. The search range is given as a positive angle in radians. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. For the point matcher, the search time is not affected by the rotation range. A too narrow range will remove all tentative matches. If prior orientation information is known, the prior rotation can be set to allow a more narrow search range. The final search range is then up to plus/minus the search range parameter starting from the prior rotation. These parameters can be updated in a teached matcher without re-teaching. When pose type is set to RIGID or SIMILARITY, setting the rotation range to zero will force the matcher to look for pure translations, or translation and scaling only.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

rotationRad

FLOAT

Angle in radians, the maximum deviation from the original object orientation to search for. The default value is PI. Input is silently clamped to the range from 0 to PI.

priorRotationRad

FLOAT

Optional prior orientation in radians. If specified, the orientation search range is centered around this orientation. Default is zero (i.e. same orientation as teach object).

Sample
Image.Matching.PointMatcher.setRotationRange(matcher, rotationRad)
setScaleRange()
Short description

Sets scale interval where objects are expected to appear. Tentative objects with a scale outside the scale range are discarded. Default range is from 0.5 to 2.0, searching for object from half to twice the size of the teach object. For transform types without a specific scale (affine and homogeneous), an approximate apparent scale is used. The scale range is ignored when the matcher is in rigid mode. For the point matcher, the search time is not affected by the scale range. A too narrow range will remove all tentative matches. An optional prior scale can be set, this affects both the minimum and maximum scale (both limits are multiplied with the prior scale). The prior scale accepts a larger range of values than the min and max scale parameters. If the object to find has a fixed non-unit scale relative to the teach object, or if prior information on the scale of the object is available, use the prior scale. The default value is 1.0. By setting both minScale and maxScale to 1.0, scale search is disabled but the prior scale parameter still has effect. These parameters can be updated in a teached matcher without re-teaching.

Parameters
Name Type Description

matcher

HANDLE

The instance to use.

minScale

FLOAT

The smallest scale factor to allowed.

maxScale

FLOAT

The largest scale factor to allowed.

priorScale

FLOAT

Optional prior scale factor. Set to the expected scale of the object to find, relative to the size of the teach object. E.g. 1.25 if the object to find is 25% larger than the teach object.

Sample
Image.Matching.PointMatcher.setScaleRange(matcher, minScale, maxScale)
setTimeout()
Short description

Abort the match call if the match time exceeds a user-defined number of seconds. The default value is 5 seconds.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

timeoutSeconds

FLOAT

Time in seconds after which the algorithm should abort.

Sample
Image.Matching.PointMatcher.setTimeout(locator, timeoutSeconds)
teach()
Short description

Teaches an object model from an image. Use getModelPoints after teach to visualize the detected salient points on the teach object.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

teachImage

CONST_OBJECT Image

The teach image.

teachRegion

CONST_AUTO

A pixel region or closed 2D shape defining which area to consider as containing the object.

Return values
Name Type Description

teachPoseTransform

OBJECT Transform

Pose transform of the object model, or nil if unsuccessful.

Sample
teachPose = Image.Matching.PointMatcher.teach(locator, teachImage, teachRegion)
toString()
Short description

Get a user-friendly string description of the matcher. The parameters are the internal parameters of the matcher, call teach for parameter changes to take effect and appear in the description string.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

Return values
Name Type Description

description

STRING

User-friendly description of the matcher.

Sample
description = Image.Matching.PointMatcher.toString(locator)

Image.OCR

Image.OCR.Halcon

Functions

findTextLineOrientation()
Short description

Finds the orientation of a text line in an image. The text line is assumed to be darker than the background

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region where the text line is located

image

CONST_OBJECT Image

Input sample

charHeightPix

INT

Character height

orientationFromRad

FLOAT

Start of search interval

orientationToRad

FLOAT

End of search interval

Return values
Name Type Description

orientationAngleRad

FLOAT

Orientation of text line in radians

Sample
local orientationAngleRad = Image.OCR.Halcon.findTextLineOrientation(region, image, charHeightPix, orientationFromRad, orientationToRad)
rotateImage()
Short description

Rotates an image.

Parameters
Name Type Description

image

CONST_OBJECT Image

Input image

orientationAngleRad

FLOAT

Orientation of text line in radians

Return values
Name Type Description

rotatedImage

OBJECT Image

The rotated image

Sample
local rotatedImage = Image.OCR.Halcon.rotateImage(image, phi)

Image.OCR.Halcon.AutoSegmenter

Short description

Automatically segments text in an image.

Functions

create()
Short description

Creates an instance of a OCR.Halcon.AutoSegmenter.

Return values
Name Type Description

handle

HANDLE

Instance handle of the AutoSegmenter.

Sample
handle = Image.OCR.Halcon.AutoSegmenter.create()
findText()
Short description

Segments an image into text lines and characters.

Parameters
Name Type Description

handle

HANDLE

Instance handle of the configuration.

image

CONST_OBJECT Image

Input sample

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the find text operation is only performed within the bounding box of is region. This can save a lot of computation time if the region is small.

Return values
Name Type Description

textLines

OBJECT Image.OCR.Halcon.SegmenterResult

Result with found text lines.

Sample
local textLines = Image.OCR.Halcon.AutoSegmenter.findText(handle, image)
setParameter()
Short description

Sets a parameter used to help/guide the automatic segmentation of the image into text lines.

Parameters
Name Type Description

handle

HANDLE

Instance handle of the configuration.

paramName

ENUM AutoSegmentationParameters

Name of parameter.

paramValue

AUTO

Flexible parameter to set a segmentation parameter. Could be a string, an integer value or a float value.

Sample
Image.OCR.Halcon.AutoSegmenter.setParameter(handle, paramName, paramValue)

Image.OCR.Halcon.FontClassifier

Short description

Classifies text in an image using a pre-trained font classifier.

Functions

classifyCharacters()
Short description

Finds characters in one text line. The text line must first be segmented into individual characters and supplied as a vector of pixelregions.

Parameters
Name Type Description

handle

HANDLE

Instance handle of the configuration.

textline

CONST_OBJECT Image.PixelRegion

Array of pixel regions each containing a text character

image

CONST_OBJECT Image

Image with text

expression

STRING

Regular expression (Perl Compatible Regular Expressions) defining the allowed set of characters

Return values
Name Type Description

characters

STRING

Classified characters. If the used fonts has a rejection class (name ends with _REJ) the ASCII code \x1A is returned whenever a character can not be classified

confidence

FLOAT

The confidence for each found character

regExpScore

FLOAT

The score for how well the found characters match the regular expression. Set to 1.0 if no expression is used.

Sample
local characters, confidence, regExpScore = Image.OCR.Halcon.FontClassifier.classifyCharacters(handle, textline, image, expression)
create()
Short description

Creates an instance of a OCR.Halcon.FontClassifier

Return values
Name Type Description

handle

HANDLE

Instance handle of the FontClassifier.

Sample
handle = Image.OCR.Halcon.FontClassifier.create()
setFont()
Short description

Set which pre-trained font classifier to used. Font names ending with _Rej have a rejection class. With fonts that provide a rejection class, it is possible to distinguish characters from background clutter. Fonts with a rejection class return the ASCII Code 26, which is SUB (substitute) if no letter was found.

Parameters
Name Type Description

handle

HANDLE

Instance handle of the configuration.

fontName

ENUM PreTrainedFonts

Name of pre-trained font. Default value: 'INDUSTRIAL_REJ'

Sample
Image.OCR.Halcon.FontClassifier.setFont(handle, mode, fontName)

Image.OCR.Halcon.ManualSegmenter

Short description

Segments text in an image based on user input.

Functions

create()
Short description

Creates an instance of a OCR.Halcon.ManualSegmenter.

Return values
Name Type Description

handle

HANDLE

Instance handle of the ManualSegmenter.

Sample
handle = Image.OCR.Halcon.ManualSegmenter.create()
findText()
Short description

Segments an image into text lines and characters.

Parameters
Name Type Description

handle

HANDLE

Instance handle of the configuration.

image

CONST_OBJECT Image

Input sample

region

CONST_OBJECT Image.PixelRegion

Optional region of interest. If supplied, the filter operation is only performed within the bounding box of is region. This can save a lot of computation time if the region is small.

Return values
Name Type Description

textLines

OBJECT Image.OCR.Halcon.SegmenterResult

Result with found text lines.

Sample
local textLines = Image.OCR.Halcon.ManualSegmenter.findText(handle, image)
setParameter()
Short description

Sets a parameter used when segmenting the image for text lines.

Parameters
Name Type Description

handle

HANDLE

Instance handle of the configuration.

paramName

ENUM ManualSegmentationParameters

Name of parameter.

paramValue

AUTO

Flexible parameter to set a segmentation parameter. Could be a string, an integer value or a float value.

Sample
Image.OCR.Halcon.ManualSegmenter.setParameter(handle, paramName, paramValue)

Image.OCR.Halcon.SegmenterResult

Short description

Segmentation result from either the ManualSegmenter or the AutoSegmenter. Contains all found text lines. Each text line is stored as a vector of PixelRegions.

Functions

getNumberOfTextLines()
Short description

Returns the number of found text lines.

Parameters
Name Type Description

result

CONST_OBJECT Image.OCR.Halcon.SegmenterResult

The segmentation result to use.

Return values
Name Type Description

numTextLines

INT

The number of text lines.

Sample
numTextLines = Image.OCR.Halcon.SegmenterResult.getNumberOfTextLines(result)
getTextLine()
Short description

Returns the text line with the given index.

Parameters
Name Type Description

result

CONST_OBJECT Image.OCR.Halcon.SegmenterResult

The segmentation result to use.

index

INT

Index of the text line.

Return values
Name Type Description

textLine

OBJECT Image.PixelRegion

The text line as a vector of PixelRegions.

Sample
textLine = Image.OCR.Halcon.SegmenterResult.getTextLine(result, index)

Image.PixelRegion

Short description

A PixelRegion represents a collection of pixels in an image. A common use-case is to represent regions or masks in an image and the underlying representation is therefore run-length coded in form of a list of connected row-segments. This makes the representation computationally efficient to work with. The pixels in a PixelRegion need not be connected though, but can consist of isolated pixels or a set of connected regions. It is assumed that a PixelRegion is used together with an Image object in which it defines the collection of pixels. The PixelRegion therefore knows only about pixel coordinates and is not aware of the Image object’s world coordinate system. For measurements inside the given PixelRegion or for transformations of the PixelRegion requiring the Image world coordinate system, the reference Image object must also be supplied as parameter to the corresponding functions. The PixelRegion can be obtained as a rasterized Shape object, but there is currently no function for converting a PixelRegion to a Shape object. A PixelRegion can be generated from an Image object, for example through a threshold operation, and it is possible to render a PixelRegion back into an Image object.

Functions

contains()
Short description

Return true if the region(s) contains the given point. If more than one region is provided true is returned if the point is inside any of the regions. If more than one point is provided an array is returned with one value for each input point.

Keywords

included, inside

See also

Shape.contains

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region(s)

point

CONST_OBJECT Point

Input point(s)

Return values
Name Type Description

result

BOOL

True if the point is within the region(s), otherwise false

Sample
result = Image.PixelRegion.contains(region, point)
countBorderPixels()
Short description

Return the number of border pixels of the region. A border pixel is located within the region and with neighboring pixels outside the region. 4-connectivity is used for the neighbor relation.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

Return values
Name Type Description

pixelCount

INT

Computed number of border pixels (single value or list)

Sample
pixelCount = Image.PixelRegion.countBorderPixels(region)
countHoles()
Short description

Return the number of holes in the region. To avoid including very small holes that only represent image noise, consider performing a dilate operation before calling countHoles.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

Return values
Name Type Description

holeCount

INT

Computed number of holes (single value or list)

Sample
holeCount = Image.PixelRegion.countHoles(region)
countPixels()
Short description

Return the number of pixels within the region.

Keywords

area

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

Return values
Name Type Description

pixelCount

INT

Computed number of pixels (single value or list)

Sample
pixelCount = Image.PixelRegion.countPixels(region)
createCircle()
Short description

Create a pixel region containing all pixels within the given circle. By providing vectors of centers and radii several pixel regions can be created. All vectors must be of equal length.

Parameters
Name Type Description

center

CONST_OBJECT Point

Circle center. Can also be a vector to create several regions.

radius

FLOAT

Circle radius. Can also be a vector to create several regions.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

The created pixel region, or vector of pixel regions for vector input.

Sample
region = Image.PixelRegion.createCircle(Point.create(100,100), 20)
createEmpty()
Short description

Create an empty region.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

The created empty pixel region.

Sample
region = Image.PixelRegion.createEmpty()
createFromPoints()
Short description

Create a PixelRegion from a set of 2D points defined in image world coordinates. Any points outside the reference image bounds are ignored. By default, each point sets one pixel in the output region. The region point size can be adjusted by the pointDiameter parameter.

Keywords

toPixelRegion

Parameters
Name Type Description

points

CONST_OBJECT Point

List of world coordinates, represented as 2D Point objects, for each pixel in the region.

referenceImage

CONST_OBJECT Image

Reference image, defines the image world coordinate system.

pointDiameter

INT

Diameter of the points to create, in pixels. Point diameter must be odd and positive. Optional, default is one.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

The generated pixel region

Sample
region = Image.PixelRegion.createFromPoints(points, referenceImage, pointDiameter)
createRectangle()
Short description

Create a pixel region containing all pixels within a rectangle with upper-left corner (x0,y0) and lower-right corner (x1,y1). By providing vectors of corners several pixel regions can be created. All vectors must be of equal length.

Parameters
Name Type Description

x0

INT

x0 (upper-left). Can also be a vector to create several regions.

y0

INT

y0 (upper-left). Can also be a vector to create several regions.

x1

INT

x1 (lower-right). Can also be a vector to create several regions.

y1

INT

y1 (lower-right). Can also be a vector to create several regions.

Return values
Name Type Description

region

OBJECT Image.PixelRegion

The created pixel region, or vector of pixel regions for for vector input.

Sample
region3 = Image.PixelRegion.createRectangle(x0, y0, x1, y1)
dilate()
Short description

Dilate the input region with a disc of the given pixel diameter.

Keywords

morphology, expand

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or list of regions.

diameter

INT

Disc diameter in pixels (must be odd).

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Dilated region or list of regions, or nil on error.

Sample
outputRegion = Image.PixelRegion.dilate(region, diameter)
downsample()
Short description

Downsample the pixel region(s) by an integer factor, keeping only rows and columns with coordinates equal to n*factor, where n = 0,1,2,…​

Parameters
Name Type Description

inputRegion

CONST_OBJECT Image.PixelRegion

Input region(s).

factor

INT

Downsample factor. Must be larger than zero.

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Input region(s) downsampled by the provided factor.

Sample
outputRegion = Image.PixelRegion.downsample(inputRegion, 2)
erode()
Short description

Erode the input region with a disc of the given pixel diameter.

Keywords

morphology, shrink

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or list of regions.

diameter

INT

Disc diameter in pixels (must be odd).

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Eroded region or list of regions, or nil on error.

Sample
outputRegion = Image.PixelRegion.erode(region, diameter)
fillHoles()
Short description

Fill any holes in a region.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region.

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Output region, where any holes in the input region has been filled.

Sample
outputRegion = Image.PixelRegion.fillHoles(region)
fillRegion()
Short description

Set all pixels within the given region(s) in the target image to a specific value in world coordinates. The pixels outside the input region keep their original values. A new image with updated values is returned, and the input image is left unchanged. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. If the value parameter is outside the image value range it will be clamped to the closest valid value. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is kept in the output image, but the pixels in the fill region will be updated with non missing data.

Keywords

inpaint, flood

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

The region(s) to fill.

value

FLOAT

World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image.

inputImage

CONST_OBJECT Image

Input image.

Return values
Name Type Description

outputImage

OBJECT Image

Result image or nil if operation failed.

Sample
outputImage = Image.PixelRegion.fillRegion(region, value, inputImage)
fillRegionInplace()
Short description

Inplace version of the Image.PixelRegion.fillRegion function that modifies the input image. See base function for full documentation.

Keywords

inpaint, flood

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

The region(s) to fill.

value

FLOAT

World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image.

image

OBJECT Image

The image. This image is overwritten with the result image.

Return values
Name Type Description

result

OBJECT Image

Reference to the result image.

Sample
result = Image.PixelRegion.fillRegionInplace(region, value, image)
findConnected()
Short description

Find the connected components of an input pixel region, i.e., splits a PixelRegion object into a list of separated regions. Only keeps regions with a size (counted in number of pixels) within the range [minSize, maxSize].

Keywords

blob extraction, labeling, connected components

Parameters
Name Type Description

inputRegions

CONST_OBJECT Image.PixelRegion

Input region(s)

minSize

INT

Minimum output region size

maxSize

INT

Maximum output region size

maxRegionCount

INT

Maximum number of output regions to return (default is 1000). Used to limit the memory requirements of the algorithm.

Return values
Name Type Description

result

OBJECT Image.PixelRegion

List of connected components represented as pixel regions, sorted by decreasing size

Sample
regions = Image.PixelRegion.findConnected(inputRegion, 10)
getArea()
Short description

Return the area of the specified region. This is equal to the number of pixels in the region times the area of each pixel as specified by the pixel sizes in the x,y-dimensions. Missing data handling: Any missing data information of the referenceImage is ignored. The area is calculated purely on the pixelRegion and scaled using the pixel scale of the image world coordinate system.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

referenceImage

CONST_OBJECT Image

Reference image, defining the image world coordinate system.

Return values
Name Type Description

area

FLOAT

Region area or areas in world units

Sample
area = Image.PixelRegion.getArea(region, referenceImage)
getBorderRegion()
Short description

Get the border pixels of the input region as a new pixel region. Border pixels are pixels within the input region bordering to pixels outside the region.

Keywords

edge, perimeter

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or list of regions

Return values
Name Type Description

borderRegion

OBJECT Image.PixelRegion

Output border region or list of regions

Sample
outputRegion = Image.PixelRegion.getBorderRegion(region)
getBoundingBox()
Short description

Return an axis-aligned box of the region as a rectangle Shape in image world coordinates. To get the bounding box in pixel coordinates instead, just omit the optional referenceImage parameter.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list.

referenceImage

CONST_OBJECT Image

Reference image, defining the image world coordinate system.

Return values
Name Type Description

box

OBJECT Shape

Bounding box, represented as a rectangle Shape object, always with zero rotation (single box or list).

Sample
box = Image.PixelRegion.getBoundingBox(region)
getBoundingBoxOriented()
Short description

Returns the rectangle (not necessarily axis-aligned) of minimum area containing the object. The area is computed in world coordinates. The rectangle is oriented such that the width is larger or equal to the height and with the orientation angle in the range (0..PI).

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

referenceImage

CONST_OBJECT Image

Reference image, used to define the image world coordinate system

accuracyRad

FLOAT

Required accuracy of the rotation (maximal error of the reported rotation, in radians). Affects both accuracy and speed.

Return values
Name Type Description

rectangle

OBJECT Shape

The computed oriented bounding box, represented as a rectangle Shape object (single object or list)

Sample
rectangle = Image.PixelRegion.getBoundingBoxOriented(region, referenceImage)
getCenterOfGravity()
Short description

Return the center of gravity of the region in image world coordinates. Missing data handling: Any missing data information of the referenceImage is ignored. The center of gravity is calculated purely on the pixelRegion compensated for image scale and origin.

Keywords

cog

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

referenceImage

CONST_OBJECT Image

Reference image, defining the image world coordinate system

Return values
Name Type Description

point

OBJECT Point

Center of gravity represented as a 2D Point object (single point or list of points)

Sample
point = Image.PixelRegion.getCenterOfGravity(region, referenceImage)
getCircularity()
Short description

Returns a circularity measure that is 1.0 for ideal circles and smaller for other shapes. The measure is robust to high-frequency noise like jagged edges along the circle perimeter, so even noisy circles get a measure close to 1.0. The measure is significantly lower if the overall appearance is rather an ellipse, square or other non-circular shape.

Keywords

roundness

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

Return values
Name Type Description

circularity

FLOAT

The computed circularity measure (single value or list)

Sample
circularity = Image.PixelRegion.getCircularity(region)
getCompactness()
Short description

Returns the compactness measure of the region (4 * PI * Area / Perimeter^2). This is close to 1.0 for circles and smaller for less compact regions.

Keywords

roundness

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

referenceImage

CONST_OBJECT Image

Reference image, used to define the image world coordinate system

Return values
Name Type Description

compactness

FLOAT

The computed compactness measure (single value or list)

Sample
compactness = Image.PixelRegion.getCompactness(region, referenceImage)
getConvexHull()
Short description

Get the convex hull of the input pixel region.

Parameters
Name Type Description

sourceRegion

CONST_OBJECT Image.PixelRegion

Input region or list of regions

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Target region or list of regions, convex hull of the input

Sample
outputRegion = Image.PixelRegion.getConvexHull(sourceRegion)
getConvexity()
Short description

Returns the convexity measure of the region (region area divided by area of convex hull). This is 1.0 for convex regions and smaller the more non-convex the region is

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

Return values
Name Type Description

convexity

FLOAT

The computed convexity measure (single value or list)

Sample
convexity = Image.PixelRegion.getConvexity(region)
getDifference()
Short description

Get the set difference of the input regions. Returns a new region containing all pixels present in the first region but not in the second. If two regions are give, the function returns the difference of the two regions. If one list and one region is given, the function returns a list of regions containing the differences of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise difference of the regions in the lists. The lists must be the same length.

Parameters
Name Type Description

region1

CONST_OBJECT Image.PixelRegion

First input region, or list of regions

region2

CONST_OBJECT Image.PixelRegion

Second input region, or list of regions

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Resulting region or list of regions

Sample
outputRegion = Image.PixelRegion.getDifference(region1, region2)
getElongation()
Short description

Get the elongation of the region, defined as the ratio between the principal axes lengths. This measure is also often called eccentricity. The value is 1.0 for circles larger than 1.0 for regions that are elongated in one direction.

Keywords

eccentricity

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

referenceImage

CONST_OBJECT Image

Reference image, used to define the image world coordinate system

Return values
Name Type Description

elongation

FLOAT

Computed elongation measure (single value or list)

Sample
elongation = Image.PixelRegion.getElongation(region, referenceImage)
getHistogram()
Short description

Get a histogram of the image values within the specified region. If the image supports missing data, pixels marked as missing are not included in the histogram. If a pixel-world mapping is specified, the histogram is computed using world coordinates. If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. Optionally, a reference surface in world coordinates may be provided, in which case the histogram is based on deviations from the reference surface. The default surface is the plane z=0. See also Image.getHistogram.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Region specifying which parts of the image to include in the histogram

image

CONST_OBJECT Image

Input image, specifying values to use in the histogram

binCount

INT

Number of bins. Uses 32 bins as default.

minValue

FLOAT

Minimum of the value range to cover. Uses an automatic range if omitted.

maxValue

FLOAT

Maximum of the value range to cover. Uses an automatic range if omitted.

referenceSurface

CONST_OBJECT Shape3D

Zero-reference surface for the histogram. Optional, default is the plane z=0.

Return values
Name Type Description

histogram

FLOAT

Histogram, represented as a vector of floats

binCenters

FLOAT

The center of each histogram bin in the input value range

Sample
histogram, centers = Image.PixelRegion.getHistogram(region, image, 64)
getIntersection()
Short description

Get the set intersection of two regions. If two regions are give, the function returns the set intersection of the two regions. If one list and one region is given, the function returns a list of regions containing the intersections of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise intersection of the regions in the lists. The lists must be the same length.

Parameters
Name Type Description

region1

CONST_OBJECT Image.PixelRegion

First input region, or list of regions

region2

CONST_OBJECT Image.PixelRegion

Second input region, or list of regions, subtracted from region1

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Resulting region or list of regions

Sample
outputRegion = Image.PixelRegion.getIntersection(region1, region2)
getMedian()
Short description

Get the median value of the pixels within the region, a special case of Image.PixelRegion.getPercentiles. The median is derived from a histogram and it is approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0.

Keywords

percentile, statistics

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

image

CONST_OBJECT Image

Input image, defines the image from which to get pixel value input.

referenceSurface

CONST_OBJECT Shape3D

Zero-reference 3D surface plane for pixel world coordinate values. Optional, default is the plane z=0.

Return values
Name Type Description

median

FLOAT

The approximate median.

Sample
median = Image.PixelRegion.getMedian(region, image, referenceSurface)
getPercentiles()
Short description

Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. All values are derived from a histogram and are approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0.

Keywords

statistics

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region

image

CONST_OBJECT Image

Input image, defines the image from which to get pixel value input.

percentileLevels

FLOAT

Percentile levels in the range (0..1)

referenceSurface

CONST_OBJECT Shape3D

Zero-reference 3D surface plane for pixel world coordinate values. Optional, default is the plane z=0.

Return values
Name Type Description

values

FLOAT

Output values

Sample
values = Image.PixelRegion.getPercentiles(region, image, percentileLevels, referenceSurface)
getPerimeterLength()
Short description

Get the region perimeter length in world units. The length is computed as the sum of distances between individual pixels. Note that this means that the reported perimeters are different than the analytical perimeter for mathematical objects like circles and rectangles.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

referenceImage

CONST_OBJECT Image

Reference image, used to define the image world coordinate system.

Return values
Name Type Description

perimeterLength

FLOAT

Computed perimeter length in world units (single value or list)

Sample
perimeterLength = Image.PixelRegion.getPerimeterLength(region, referenceImage)
getPrincipalAxes()
Short description

Get principal axes of the region (orientation and length of major/minor axes, derived from region moments).

Keywords

PCA, covariance, eccentricity, elongation, major, moment, minor

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region

referenceImage

CONST_OBJECT Image

Reference image, defines the image world coordinate system.

Return values
Name Type Description

angleRad

FLOAT

Rotation angle of the major axis in radians.

majorAxisWorld

FLOAT

Length of the major axis in world units

minorAxisWorld

FLOAT

Length of the minor axis in world units

Sample
angleRad, majorAxisWorld, minorAxisWorld = Image.PixelRegion.getPrincipalAxes(region, referenceImage)
getStatistics()
Short description

Get pixel value statistics for pixels belonging to a pixel region. Image world coordinate system values are used and pixels with missing data are excluded. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided, basing the statistics on deviations from that surface. If the statistics can not be calculated, nil is returned. A vector of regions can be provided, in which case four vectors of statistics are returned, one entry for each input region. Any invalid input region in the vector will have the corresponding output entries set to zero.

Keywords

average, max, maximum, min, minimum, standard deviation, std, mean

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region, defines the region of image in which to gather statistics, or several regions where statistics are calculated individually for each region.

image

CONST_OBJECT Image

Input image, defines the image from which to get pixel value input.

referenceSurface

CONST_OBJECT Shape3D

Reference surface, defines the zero level in world coordinates. Default is the plane z=0.

Return values
Name Type Description

min

FLOAT

Minimal value, or vector of values with one entry for each region.

max

FLOAT

Maximal value, or vector of values with one entry for each region.

average

FLOAT

Average value, or vector of values with one entry for each region.

standardDeviation

FLOAT

Standard deviation, or vector of standard deviations with one entry for each region.

Sample
min, max, average, standardDeviation = Image.PixelRegion.getStatistics(region, image, referenceSurface)
getUnion()
Short description

Get the set union of two or more regions. If two regions are give, the function returns the set union of the two regions. If one list of regions is given, the function returns the set union of all regions in the list. If one list and one region is given, the function returns a list of regions containing the unions of each region in the list and the single region. If two lists are given, the function returns a vector of regions containing the pair-wise unions of the regions in the lists. The lists must be the same length.

Parameters
Name Type Description

region1

CONST_OBJECT Image.PixelRegion

First input region or list of regions

region2

CONST_OBJECT Image.PixelRegion

Second input region or list of regions

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Resulting region or list of regions

Sample
outputRegion = Image.PixelRegion.getUnion(region1, region2)
getVolume()
Short description

Get the volume between a height map and a reference surface within the region or regions. Image world coordinate system values are used. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided. NOTE: Values below the reference surface are disregarded (counted as a zero-volume-contribution). Pixels with missing data are disregarded (counted as a zero-volume-contribution). For other ways of handling missing data, such as filling using nearby data, call the appropriate Image.missingData-function before calling getVolume.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list.

heightMap

CONST_OBJECT Image

Input image that can be interpreted as a height map using the origin and pixelSize properties.

referenceSurface

CONST_OBJECT Shape3D

Reference surface, defines the zero level in world coordinates. Default is the plane z=0.

Return values
Name Type Description

volume

FLOAT

The volume contained below the height map within the input region (single value or list), or nil in case of failure.

Sample
volume = Image.PixelRegion.getVolume(region, heightMap)
intersectImage()
Short description

Get the part of a pixel region within a reference image.

Keywords

complement, difference

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or list of regions.

referenceImage

CONST_OBJECT Image

Reference image, defines the area for cropping the region.

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

The part of region or list of regions within referenceImage, or nil on error.

Sample
outputRegion = Image.PixelRegion.intersectImage(region, referenceImage)
invert()
Short description

Get the complement within a reference image, returns a pixel region(s) containing all reference image pixels not in the input region(s).

Keywords

complement

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region(s).

referenceImage

CONST_OBJECT Image

Reference image, defines the area for inverting the region(s).

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

The complement(s) to region(s) within referenceImage, or nil on error.

Sample
outputRegion = Image.PixelRegion.invert(region, referenceImage)
isEmpty()
Short description

Check if the region contains zero pixels. If a vector of pixel regions is provided the output is a vector of the same length.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input pixel region. Can also be a vector of pixel regions.

Return values
Name Type Description

isEmpty

BOOL

True if the region is empty. Can also be a vector of booleans.

Sample
isEmpty = Image.PixelRegion.isEmpty(region)
thin()
Short description

Creates a skeleton region out of the input region.

Keywords

morphology, skeleton

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or list of regions.

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Skeleton region

Sample
outputRegion = Image.PixelRegion.thin(region)
toImage()
Short description

Convert the region to an image, using a specified value for pixels within the region. The value is in world coordinates and is clamped to the representable range of the image.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region

referenceImage

CONST_OBJECT Image

Reference image, defines the size, pixel type and image world coordinate system of the output image.

valueWorld

FLOAT

World coordinate value to use within the region, default is 255

Return values
Name Type Description

outputImage

OBJECT Image

Image containing the region

Sample
outputImage = Image.PixelRegion.toImage(region, referenceImage, valueWorld)
toPoints2D()
Short description

Get a vector of the pixels contained in the region represented as 2D Point objects. Pixel coordinates are converted to image world coordinates using the reference image. Any parts of the input region that is outside the reference image bounds is ignored.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

The region to process

referenceImage

CONST_OBJECT Image

Reference image, defines the image world coordinate system

Return values
Name Type Description

points

OBJECT Point

Vector of 2D Point objects, expressed in image world coordinates, for each pixel contained within the region.

Sample
points = Image.PixelRegion.toPoints2D(region, referenceImage)
toPoints3D()
Short description

Get a vector of the pixels contained in the region represented as 3D Point objects, including a z value from the reference image. Any parts of the input region that is outside the image bounds or contains missing data is ignored.

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

The region to process

referenceImage

CONST_OBJECT Image

Input image, defines the pixel-world mapping and is used to get z values (pixel values converted using the z-part of the pixel-world mapping)

Return values
Name Type Description

points

OBJECT Point

Vector of 3D Point objects, expressed in image world coordinates, for each pixel contained within the region.

Sample
points = Image.PixelRegion.toPoints3D(region, referenceImage)
toString()
Short description

Get a brief string description of the pixel region. This is equal to the text shown in the debugger to describe the region. Can also be called with a vector of pixel regions.

Keywords

description, help, print

Parameters
Name Type Description

pixelRegion

CONST_OBJECT Image.PixelRegion

Input pixel region. Can also be a vector of pixel regions.

Return values
Name Type Description

str

STRING

Description of the region. If the input is a vector the output is a vector of strings.

Sample
print("Description: " .. Image.PixelRegion.toString(pixelRegion))
touchesImageBorder()
Short description

Returns true if a pixel region touches the border of provided image

Parameters
Name Type Description

region

CONST_OBJECT Image.PixelRegion

Input region or region list

referenceImage

CONST_OBJECT Image

Input image, used only to define the image size

Return values
Name Type Description

touches

BOOL

True if region touches image borders (single value or list)

Sample
outputRegion = Image.PixelRegion.touchesImageBorder(region, referenceImage)
transform()
Short description

Transform the region using a general 2D Transform object, expressed in image world coordinates.

See also

Image.transform

Parameters
Name Type Description

inputRegion

CONST_OBJECT Image.PixelRegion

Input region, or a list of regions

transform

CONST_OBJECT Transform

Transform to apply, expressed in world coordinates

referenceImage

CONST_OBJECT Image

Reference image, used to define the image world coordinate system

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

The transformed pixel region or region list

Sample
outputRegion = Image.PixelRegion.transform(region, transform, referenceImage)

Image.PixelRegion.Filter

Short description

Filter for pixel regions. Offers convenient filtering and sorting based on all features from Image.PixelRegion. The description of each filter contains a reference to the corresponding function.

Keywords

blobs, extraction, sorting, features

Functions

apply()
Short description

Apply the filter to a region list. Return the filtered and sorted regions. The actual regions are copied by reference, so changing a region in the input list makes the same region change also in the output list and vice versa. Note that lists in Lua are 1-indexed and matrices are 0-indexed, so the features corresponding to filteredRegions[i] is at row i-1 in the featureValues matrix. If no blobs are found, the function returns an empty filteredRegions list and no featureValues matrix.

Parameters
Name Type Description

filter

OBJECT Image.PixelRegion.Filter

Filter to apply

inputRegions

OBJECT Image.PixelRegion

Input regions

inputImage

OBJECT Image

Input image, used for pixel-world mapping and for pixel values if value statistics features are used (median, average, etc.)

Return values
Name Type Description

filteredRegions

OBJECT Image.PixelRegion

Filtered and sorted output regions

featureValues

OBJECT Matrix

Matrix of computed feature values. Each row corresponds to an output region and each column to a computed feature. The columns are in the same order as the features are mentioned in calls to setRange and setCondition before applying the filter.

Sample
filteredRegions, featureValues = Image.PixelRegion.Filter.apply(filter, inputRegions, inputImage)
create()
Short description

Create a new PixelRegion filter

Return values
Name Type Description

filter

OBJECT Image.PixelRegion.Filter

The new filter

Sample
filter = Image.PixelRegion.Filter.create()
setCondition()
Short description

Set a new equality/inequality condition to the filter. Only regions with feature value within the given range will be included in the filter output.

Keywords

inequal, equal

Parameters
Name Type Description

filter

OBJECT Image.PixelRegion.Filter

Input filter to modify

featureType

ENUM FeatureType

The feature type that the filter applies to. Must be an integer feature type.

exactValue

INT

Exact value to compare to

equality

BOOL

Set to true for equality comparison and false for inequality. Default is equality.

Sample
Image.PixelRegion.Filter.setCondition(filter, "HOLESCOUNT", 0)
setRange()
Short description

Set a new range constraint to the filter. Only regions with feature value within the given range will be included in the filter output.

Keywords

interval

Parameters
Name Type Description

filter

OBJECT Image.PixelRegion.Filter

Input filter to modify

featureType

ENUM FeatureType

The feature type that the filter applies to

minValue

FLOAT

Minimum allowed value (inclusive)

maxValue

FLOAT

Maximum allowed value (inclusive)

withinRange

BOOL

Set to true to setup a within-range check and false for an outside-range check. Default is within-range.

Sample
Image.PixelRegion.Filter.setRange(filter, "CONVEXITY", 0.0, 0.8)
sortBy()
Short description

Defines which feature the output list shall be sorted by

Parameters
Name Type Description

filter

OBJECT Image.PixelRegion.Filter

Input filter to modify

featureType

ENUM FeatureType

The feature type to sort by

ascending

BOOL

Set to true to sort in ascending order (default), false for descending

Sample
Image.PixelRegion.Filter.sortBy(filter, "CENTROIDX")
toString()
Short description

Get a user-friendly string description of the filter

Parameters
Name Type Description

filter

OBJECT Image.PixelRegion.Filter

Input filter

Return values
Name Type Description

description

STRING

User-friendly description of the filter

Sample
print("The filter is: " .. Image.PixelRegion.Filter.toString(filter))

Image.Provider

Short description

Provides functionality to control and receive heightmap images from the camera of the programmable device.

Overview

Image.Provider.Camera

Short description

Provides functionality to control and receive images from the camera of the programmable device.

Functions

create()
Short description

Creates an instance of the image provider, which provides images asynchronously. Will return nil if there already exists a handle of this CROWN.

Return values
Name Type Description

handle

HANDLE

ImageProviderCam exists as long as this handle.

Sample
handle = Image.Provider.Camera.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

register()
Short description

This function is used to register for any event of this provider. The event name is specified as parameter.

Parameters
Name Type Description

handle

HANDLE

Handle returned by create

eventname

STRING

The event to register to

callback

STRING

name of function to call upon the event

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

Sample
Image.Provider.Camera.register(handle, "OnNewImage", "HandleNewImage")
setConfig()
Short description

Applies the given configuration to the camera provider. Can cause minor errors if called during active image acquisition.

Parameters
Name Type Description

handle

HANDLE

Instance handle of the Camera provider.

configHandle

HANDLE

Handle of config instance to apply.

Return values
Name Type Description

success

BOOL

true if new value could be set in configuration

Sample
Image.Provider.Camera.setConfig(camHandle, configHandle)
start()
Short description

Triggers the camera to start taking images explicitly.

Parameters
Name Type Description

handle

HANDLE

Handle returned by create

Return values
Name Type Description

success

BOOL

True if call to start succeeded and image acquisition was started.

Sample
Image.Provider.Camera.start(handle)
stop()
Short description

Stops taking images explicitly.

Parameters
Name Type Description

handle

HANDLE

Handle returned by create

Sample
Image.Provider.Camera.stop(handle)
trigger()
Short description

Trigger images explicitly. Image trigger mode must be set to "SOFTWARE" by Image.Provider.Camera.V3TConfig3D.setImageTriggerMode().

Parameters
Name Type Description

handle

HANDLE

The instance to use

abortOngoing

BOOL

If true any ongoing image acquisition is aborted before triggering. Default set to false

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.trigger(handle, true)

Events

OnNewImage
Short description

The image event which is thrown for every image.

Parameters
Name Type Description

handle

HANDLE

Handle returned by create

image

OBJECT Image

the captured image

sensorData

OBJECT SensorData

additional data belonging to the image

Image.Provider.Camera.V3TConfig2D

Short description

Configuration for acquiring 2D sensor images. The sensor image is useful for viewing the apperance of the laser while configuring exposure and gain. Sensor images can also be used for 2D image analysis after disabling the laser with TriSpector.setLaserEnabled(false). Call Image.Provider.Camera.setConfig() with a V3TConfig2D to activate sensor image acquisition.

Functions

create()
Short description

Creates an instance of a V3TConfig2D.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance.

Sample
handle = Image.Provider.Camera.V3TConfig2D.create()
getExposureTime()
Short description

Get exposure time

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

exposureTime

INT

Returns configured exposure time in microseconds

Sample
exposureTime = Image.Provider.Camera.V3TConfig2D.getExposureTime(handle)
getGain()
Short description

Get gain

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

gain

FLOAT

Returns configured gain

Sample
gain = Image.Provider.Camera.V3TConfig2D.getGain(handle)
getImageTriggerMode()
Short description

Get image trigger mode

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

imageTriggerMode

ENUM ImageTriggerMode

Returns configured image trigger mode

Sample
imageTriggerMode = Image.Provider.Camera.V3TConfig2D.getImageTriggerMode(handle)
getSensorRegion()
Short description

Get sensor region

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

width

INT

Width in pixels

height

INT

Height in pixels

xOffset

INT

X-offset in pixels

yOffset

INT

Y-offset in pixels

Sample
width, height, xOffset, yOffset = Image.Provider.Camera.V3TConfig2D.getSensorRegion(handle)
setExposureTime()
Short description

Set exposure time

Parameters
Name Type Description

handle

HANDLE

The instance to use

exposureTime

INT

Exposure time in microseconds. Allowed range [1, 100000]

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig2D.setExposureTime(handle, 50)
setGain()
Short description

Set gain

Parameters
Name Type Description

handle

HANDLE

The instance to use

gain

FLOAT

Gain. Allowed range [1, 8]

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig2D.setGain(handle, 2.0)
setImageTriggerMode()
Short description

Determines how sensor images are triggered.

Parameters
Name Type Description

handle

HANDLE

The instance to use

imageTriggerMode

ENUM ImageTriggerMode

Image trigger mode

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig2D.setImageTriggerMode(handle, "SOFTWARE")
setSensorRegion()
Short description

Set the region on the image sensor to use when acquiring 2D-images.

Parameters
Name Type Description

handle

HANDLE

The instance to use

width

INT

Width in pixels. Allowed range [64, 1280]

height

INT

Height in pixels. Allowed range [24, 1024]

xOffset

INT

X-offset in pixels. Allowed range [0, 1280 - width]

yOffset

INT

Y-offset in pixels. Allowed range [0, 1024 - height]

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig2D.setSensorRegion(handle, 1280, 1024, 0, 0)
validate()
Short description

Validate the configuration settings of this V3TConfig2D. This allows testing the validity of a V3TConfig2D without setting it to a provider. Note that Image.Provider.Camera.setConfig rejects invalid instances.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

validConfig

BOOL

Returns true if the configuration settings are valid, otherwise false

Sample
valid = Image.Provider.Camera.V3TConfig2D.validate(handle)

Image.Provider.Camera.V3TConfig3D

Short description

Configuration for acquiring heightmaps. Call Image.Provider.Camera.setConfig() with a V3TConfig3D to activate heightmap acquisition.

Functions

create()
Short description

Creates an instance of a V3TConfig3D.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance.

Sample
handle = Image.Provider.Camera.V3TConfig3D.create()
get2DConfig()
Short description

Get a V3TConfig2D with the sensor settings from this V3TConfig3D. The V3TConfig2D can be used to acquire 2D sensor images for inspecting the appearance of the laser line. The V3TConfig2D sensor region is determined by the V3TConfig3D field of view.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

configHandle

HANDLE

Handle of a 2D config instance

Sample
config = Image.Provider.Camera.V3TConfig3D.get2DConfig(handle)
getEncoderTicksPerMm()
Short description

Get the configured number of encoder ticks per mm. A tick is defined as a complete cycle of an encoder channel.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

ticksPerMm

FLOAT

Returns configured encoder ticks per mm

Sample
ticksPerMm = Image.Provider.Camera.V3TConfig3D.getEncoderTicksPerMm(handle)
getExposureTime()
Short description

Get the configured exposure time.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

exposureTime

INT

Returns configured exposure time in microseconds

Sample
exposureTime = Image.Provider.Camera.V3TConfig3D.getExposureTime(handle)
getExposureTimeLimits()
Short description

Get the current limits for setExposureTime. The upper limit depends on the field of view size.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

min

INT

Minimum possible exposure time

max

INT

Maximum possible exposure time

Sample
min, max = Image.Provider.Camera.V3TConfig3D.getExposureTimeLimits(handle)
getFieldOfView()
Short description

Get the configured field of view.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

width

FLOAT

Width in mm

height

FLOAT

Height in mm

xOffset

FLOAT

X-offset in mm for the field of view center relative to the guaranteed field of view center.

zOffset

FLOAT

Z-offset in mm for the field of view center relative to the guaranteed field of view center.

Sample
width, height, xOffset, zOffset = Image.Provider.Camera.V3TConfig3D.getFieldOfView(handle)
getFreeRunningSpeed()
Short description

Get the configured movement speed for free running profile trigger mode.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

freeRunningSpeed

FLOAT

Returns configured motion speed for free running mode in mm/s

Sample
speed = Image.Provider.Camera.V3TConfig3D.getFreeRunningSpeed(handle)
getFreeRunningSpeedLimits()
Short description

Get the current limits for setFreeRunningSpeed. The upper limit depends on the profile distance, the field of view size and (in some cases) the exposure time.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

min

FLOAT

Minimum possible free running speed

max

FLOAT

Maximum possible free running speed

Sample
min, max = Image.Provider.Camera.V3TConfig3D.getFreeRunningSpeedLimits(handle)
getGain()
Short description

Get the configured image sensor gain.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

gain

FLOAT

Returns configured gain

Sample
gain = Image.Provider.Camera.V3TConfig3D.getGain(handle)
getGuaranteedFieldOfView()
Short description

Get the guaranteed field of view. Working within this field of view guarantees that the configuration can be moved to another TriSpectorP device of the same variant. Returns nil if an invalid device variant is specified.

Parameters
Name Type Description

handle

HANDLE

The instance to use

deviceVariant

ENUM TriSpector.DeviceVariant

Device variant to get guaranteed Field Of View for. Defaults to the executing device’s variant if not specified

Return values
Name Type Description

lowerWidth

INT

Lower width in mm

upperWidth

INT

Upper width in mm

height

INT

Height in mm

xOffset

INT

X-offset in mm

zOffset

INT

Z-offset in mm

Sample
lowerWidth, upperWidth, height, xOffset, zOffset = Image.Provider.Camera.V3TConfig3D.getGuaranteedFieldOfView(handle)
getHeightmapLength()
Short description

Get the configured heightmap length.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

length

FLOAT

Length in mm

Sample
length = Image.Provider.Camera.V3TConfig3D.getHeightmapLength(handle)
getHeightmapLengthLimits()
Short description

Get the current limits for setHeightmapLength. A heightmap must contain at least 16 and at most 2500 profiles. The number of profiles is determined by the heightmap length divided by the profile distance.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

min

FLOAT

Minimum possible heightmap length in mm

max

FLOAT

Maximum possible heightmap length in mm

Sample
min, max = Image.Provider.Camera.V3TConfig3D.getHeightmapLengthLimits(handle)
getImageTriggerDelay()
Short description

Get the configured image trigger delay value and unit

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

delay

INT

Returns configured image trigger delay value

unit

ENUM ImageTriggerDelayUnit

Returns configured image trigger delay unit

Sample
delay, unit = Image.Provider.Camera.V3TConfig3D.getImageTriggerDelay(handle)
getImageTriggerMode()
Short description

Get image trigger mode

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

imageTriggerMode

ENUM ImageTriggerMode

Returns configured image trigger mode

Sample
imageTriggerMode = Image.Provider.Camera.V3TConfig3D.getImageTriggerMode(handle)
getLaserThreshold()
Short description

Get the configured laser threshold. Sensor image intensities above this threshold will be included when locating the laser peak.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

laserThreshold

INT

Returns configured laser threshold

Sample
laserThreshold = Image.Provider.Camera.V3TConfig3D.getLaserThreshold(handle)
getObjectTriggerLine()
Short description

Return the line used for object triggering.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

line

OBJECT Shape3D

3D line segment. The line used in Object Trigger.

threshold

INT

Sample
line, threshold = Image.Provider.Camera.V3TConfig3D.getObjectTriggerLine(handle)
getPeakSelectionMode()
Short description

Get peak selection mode

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

peakSelectionMode

ENUM PeakSelectionMode

Returns configured peak selection mode

Sample
mode = Image.Provider.Camera.V3TConfig3D.getPeakSelectionMode(handle)
getProfileDistance()
Short description

Get the configured distance in mm between consecutive profiles in the heightmap. Note that this is the value as specified with setProfileDistance which may differ from the actual value when using an encoder.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

profileDistance

FLOAT

Returns configured distance in mm between consecutive profiles

Sample
profileDistance = Image.Provider.Camera.V3TConfig3D.getProfileDistance(handle)
getProfileDistanceLimits()
Short description

Get the current limits for setProfileDistance. Using an encoder (ProfileTriggerMode "ENCODER"), the limits depend on the heightmap length. In free running mode the limits also depend on the free running speed, field of view size and (in some cases) the exposure time.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

min

FLOAT

Minimum possible profile distance

max

FLOAT

Maximum possible profile distance

Sample
min, max = Image.Provider.Camera.V3TConfig3D.getProfileDistanceLimits(handle)
getProfileTriggerMode()
Short description

Get profile trigger mode

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

profileTriggerMode

ENUM ProfileTriggerMode

Returns current profile trigger mode

Sample
profileTriggerMode = Image.Provider.Camera.V3TConfig3D.getProfileTriggerMode(handle)
getXResolution()
Short description

Get the configured X-resolution

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

xResolution

FLOAT

Returns configured X-resolution in mm/px

Sample
xResolution = Image.Provider.Camera.V3TConfig3D.getXResolution(handle)
getXResolutionLimits()
Short description

Get the current limits for setXResolution. The limits depend on the field of view width.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

min

FLOAT

Minimum possible x-resolution

max

FLOAT

Maximum possible x-resolution

Sample
min, max = Image.Provider.Camera.V3TConfig3D.getXResolutionLimits(handle)
setEncoderTicksPerMm()
Short description

Specify the number of ticks that are given by the encoder per mm. A tick is defined as a complete cycle of an encoder channel.

Parameters
Name Type Description

handle

HANDLE

The instance to use

ticksPerMm

FLOAT

Encoder ticks per mm. Allowed range [1, 10000]

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setEncoderTicksPerMm(handle, 58)
setExposureTime()
Short description

Set the exposure time for the image sensor. With optimal exposure time the laser appears as a gray line in sensor images. If the exposure is too high, the reflectance image will be saturated.

Parameters
Name Type Description

handle

HANDLE

The instance to use

exposureTime

INT

Exposure time in microseconds. Allowed range [1, 100000]

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setExposureTime(handle, 50)
setFieldOfView()
Short description

Set the field of view rectangle. Data outside the rectangle is excluded from heightmap profiles. A smaller field of view can allow a shorter profile distance or higher speed.

Parameters
Name Type Description

handle

HANDLE

The instance to use

width

FLOAT

Width in mm

height

FLOAT

Height in mm

xOffset

FLOAT

X-offset in mm for the field of view center relative to the guaranteed field of view center.

zOffset

FLOAT

Z-offset in mm for the field of view center relative to the guaranteed field of view center.

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setFieldOfView(handle, 200, 400, 0, 200)
setFreeRunningSpeed()
Short description

Set the movement speed of the object (or TriSpectorP device) for free running profile trigger mode. This is used with setProfileTriggerMode("FREE_RUNNING").

Parameters
Name Type Description

handle

HANDLE

The instance to use

freeRunningSpeed

FLOAT

Speed in mm/s. Allowed range [1.0, 5000.0]

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setFreeRunningSpeed(handle, 1000.0)
setGain()
Short description

Set the image sensor gain. Note that adjusting the exposure with setExposureTime is preferred over gain when possible, as gain increases noise in images.

Parameters
Name Type Description

handle

HANDLE

The instance to use

gain

FLOAT

Gain. Allowed range [1, 8]

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setGain(handle, 2.0)
setHeightmapFinishedOutput()
Short description

Digital output that will be activated when a heightmap acquisition is completed. The given output is activated when the last profile of a heightmap is acquired. This can be used to synchronize the image acquisition with an external device. The output will remain active for the duration of the activation value configured in the Connector.DigitalOut.

Parameters
Name Type Description

handle

HANDLE

The instance to use

output

AUTO

A Connector.DigitalOut instance or nil

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false.

Sample
Image.Provider.Camera.V3TConfig3D.setHeightmapFinishedOutput(handle, do4)
setHeightmapLength()
Short description

Set the heightmap length in mm. The length and profile distance determines the number of profiles in a heightmap.

Parameters
Name Type Description

handle

HANDLE

The instance to use

length

FLOAT

Length in mm

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false.

Sample
Image.Provider.Camera.V3TConfig3D.setHeightmapLength(handle, 300)
setImageTriggerDelay()
Short description

Set the image trigger delay in either ms or mm. Heightmap acquisition is delayed by the configured time or distance after triggering.

Parameters
Name Type Description

handle

HANDLE

The instance to use

delay

INT

Image trigger delay value. Allowed range [0,10000]

unit

ENUM ImageTriggerDelayUnit

Unit for the specified delay value

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setImageTriggerDelay(handle, 15, "MM")
setImageTriggerMode()
Short description

Set image trigger mode. This determines how heightmap images are triggered.

Parameters
Name Type Description

handle

HANDLE

The instance to use

imageTriggerMode

ENUM ImageTriggerMode

Image trigger mode

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setImageTriggerMode(handle, "OBJECT")
setLaserThreshold()
Short description

Set laser threshold. Sensor image intensities above this threshold will be included when locating the laser peak. A high threshold value reduces noise in the resulting heightmap, while a low threshold makes it possible to detect weak laser peaks.

Parameters
Name Type Description

handle

HANDLE

The instance to use

laserThreshold

INT

Laser threshold. Allowed range [0, 255]

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setLaserThreshold(handle, 50)
setObjectTriggerLine()
Short description

Specify a line and threshold for ImageTriggerMode "OBJECT". A heightmap acquisition is triggered if the amount of data extending above the line is greater than threshold.

Parameters
Name Type Description

handle

HANDLE

The instance to use

line

OBJECT Shape3D

3D line segment. The line must be specified in the XZ plane so Y-coordinates should be set to 0.

threshold

INT

Threshold in percent how much data should be above

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setObjectTriggerLine(handle, line, 20)
setPeakSelectionMode()
Short description

Set the peak selection mode. This determines how the laser line is detected and can help for handling reflections.

Parameters
Name Type Description

handle

HANDLE

The instance to use

peakSelectionMode

ENUM PeakSelectionMode

Peak selection mode

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setPeakSelectionMode(handle, "STRONGEST")
setProfileDistance()
Short description

Set distance in mm between consecutive profiles in the heightmap. Note that when the profileTriggerMode is set to ENCODER the actual value for profileDistance might be slightly adjusted since the number of encoder ticks between two profiles is rounded to the nearest integer.

Parameters
Name Type Description

handle

HANDLE

The instance to use

profileDistance

FLOAT

Distance in mm between consecutive profiles. Allowed range [0.01,10]

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setProfileDistance(handle, 2.0)
setProfileTriggerMode()
Short description

Set whether heightmap profiles are triggered at fixed intervals (time) or by encoder ticks (distance).

Parameters
Name Type Description

handle

HANDLE

The instance to use

profileTriggerMode

ENUM ProfileTriggerMode

Profile trigger mode

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setProfileTriggerMode(handle, "FREE_RUNNING")
setXResolution()
Short description

Set the heightmap X-resolution in mm/pixel. To improve handling of rotated objects, set the x-resolution equal to the profile distance (square pixels).

Parameters
Name Type Description

handle

HANDLE

The instance to use

xResolution

FLOAT

X-resolution in mm/px

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
Image.Provider.Camera.V3TConfig3D.setXResolution(handle, 0.8)
validate()
Short description

Validate the configuration settings of this V3TConfig3D. This allows testing the validity of a V3TConfig3D without setting it to a provider. Note that Image.Provider.Camera.setConfig rejects invalid instances.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

validConfig

BOOL

Returns true if the configuration settings are valid, otherwise false

Sample
valid = Image.Provider.Camera.V3TConfig3D.validate(handle)

Image.Provider.Directory

Short description

Image provider which provides images periodically from the filesystem. Images can be in format PNG or BMP.

Functions

create()
Short description

Creates an instance of the image directory provider, which provides images asynchronously from file-system.

Return values
Name Type Description

handle

HANDLE

Image provider exists as long as this handle exists.

Sample
dirProv = Image.Provider.Directory.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

register()
Short description

This function is used to register for any event of the image provider. The event name is specified as parameter.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this provider

eventname

STRING

The event to register to

callback

STRING

function name to call on the event

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

Sample
Image.Provider.Directory.register(dirProv, "OnNewImage", "handleNewImage")
setAutoDeleteActive()
Short description

Sets auto-delete active. This means the image is deleted from the directory after load. Default is false.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this provider

state

BOOL

If true the image file will be deleted after being loaded.

Sample
Image.Provider.Directory.setAutoDeleteActive(dirProv, true)
setCycleTime()
Short description

Sets the pause between taking images in milli seconds.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this provider

periodMs

INT

Period in [ms] between images.

Sample
Image.Provider.Directory.setCycleTime(handle, 500)
setCyclicModeActive()
Short description

Sets cyclic-mode active. Default is true.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this provider

state

BOOL

If false driver stops taking images if end of directory is reached.

Sample
Image.Provider.Directory.setCyclicModeActive(dirProv, true)
setImagePoolSizeMB()
Short description

Limits the number of mega bytes which can be acquired by capturing images and used at the same time. Default is 20.

Parameters
Name Type Description

handle

HANDLE

Instance handle of the provider.

size

INT

Size of the internal image pool in mega byte.

Sample
Image.Provider.Directory.setImagePoolSizeMB(cam, 20)
setPath()
Short description

Sets the directory and file extension(s) for the image provider from which it reads images.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this provider

path

STRING

Path to the file-system

fileextensions

STRING

Supported file extensions (comma separated).

recursive

BOOL

An optional flag whether to run through subdriectories also.

Sample
Image.Provider.Directory.setPath(dirProv, ImageInputPath)
start()
Short description

Starts taking images.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this provider

burst

INT

Leave empty or '0' for continuous acquisition. >0:=enable burst-mode with provided number of images.

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
local success = Image.Provider.Directory.start(dirProv)
stop()
Short description

Stops taking images.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this provider

Return values
Name Type Description

success

BOOL

Returns true if function call was successful, otherwise false

Sample
local stopped = Image.Provider.Directory.stop(dirProv)

Events

OnNewImage
Short description

The image event which is thrown for every new image.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this provider

image

OBJECT Image

The loaded image

sensorData

OBJECT SensorData

Supplementary data which belongs to the image

Image.Pyramid

Short description

A multiscale representation of an image. Each level in the pyramid contains an image that is downsampled a factor 2 relative to the preceding level. Level 0 of the ImagePyramid keeps the original image. There are two smoothing operators that can be used to avoid aliasing artifacts in the downsampled images: "LINEAR" and "GAUSSIAN". The default method is "LINEAR". A non-interpolating nearest neighbor method is also available, "NEAREST". The coarsest level cannot contain an image smaller than 16x16 pixels, levels below this size are not created even if more levels are specified upon ImagePyramid creation. For odd-sized images, the output size after downscaling is different for the "LINEAR" and "GAUSSIAN" cases: if the size N is odd, the output size is (N-1)/2 for "LINEAR" and "NEAREST" while it is (N+1)/2 for "GAUSSIAN". Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position when plotted on different pyramid levels. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: When using "LINEAR" or "NEAREST" as the DownsamplingMethod missing data is handled. For linear interpolation, missing data will remain if all points in the interpolation neighborhood are missing. Otherwise the missing data value will be ignored and the output will be the linear interpolation of the valid neighbors. DownsamplingMethod "GAUSSIAN", currently does not support missing data. Hardware acceleration: Some devices have FPGA-support for the pyramid generation. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. Please note that if the FPGA accelerator is busy the processing will fall-back to CPU processing. The processing may also fall-back to CPU for some unsupported configurations. The rounding done in the CPU and the FPGA version may differ slightly resulting in different values in the least significant bit of the generated pyramid levels.

Keywords

decimate, downsample, resample, scalespace, subsample, scale

Functions

create()
Short description

Create an image pyramid. If no arguments are given an unintialized pyramid will be created, which can be populated at a later stage using the Image.Pyramid.generate() function.

Parameters
Name Type Description

image

CONST_OBJECT Image

Optional: Source image. Supported image types depends on used device type.

levelCount

INT

Optional: Desired number of pyramid levels. One level will be used for the original image, so to get at least one downscaled version the levelCount parameter must be larger than 1. Note that the created ImagePyramid may contain fewer levels as the coarsest level is limited to a side of minimum 16 pixels.

method

ENUM DownsamplingMethod

Optional: The downsampling method, currently NEAREST, LINEAR or GAUSSIAN are available. Default is LINEAR.

processingUnit

ENUM ProcessingUnit

Optional: Processing Unit to use (CPU, FPGA). Default is CPU.

cloneData

BOOL

Optional: If set to true a cloned copy of the original input image is made in the pyramid object. If set to false a reference copy is made, which saves execution time and memory. Note however, any other change made later to the input image will then also affect the pyramid object. Default is true, i.e., to make a cloned copy.

Return values
Name Type Description

pyramidImage

OBJECT Image.Pyramid

The created image pyramid.

Sample
pyramidImage = Image.Pyramid.create(image, levelCount, "LINEAR", "CPU")
generate()
Short description

Generate pyramid levels for an existing image pyramid, replacing any existing data in the pyramid object. The function works inplace, i.e., the object is modified directly.

Parameters
Name Type Description

pyramidImage

OBJECT Image.Pyramid

The image pyramid.

image

CONST_OBJECT Image

Source image. Supported image types depends on used device type.

levelCount

INT

Desired number of pyramid levels. One level will be used for the original image, so to get at least one downscaled version the levelCount parameter must be larger than 1. Note that the created ImagePyramid may contain fewer levels as the coarsest level is limited to a side of minimum 16 pixels.

method

ENUM DownsamplingMethod

The downsampling method, currently NEAREST, LINEAR or GAUSSIAN are available. Default is LINEAR.

processingUnit

ENUM ProcessingUnit

Optional: Processing Unit to use (CPU, FPGA). Default is CPU.

cloneData

BOOL

Optional: If set to true a cloned copy of the original input image is made in the pyramid object. If set to false a reference copy is made, which saves execution time and memory. Note however, any other change made later to the input image will then also affect the pyramid object. Default is true, i.e., to make a cloned copy.

Return values
Name Type Description

pyramidImage

OBJECT Image.Pyramid

Reference to the pyramid with generated pyramid levels, or nil if something goes wrong. Note that the function works inplace, modifying the object directly, the output is mainly for error checking.

Sample
pyramidImage = Image.Pyramid.generate(pyramidImage, image, levelCount, "LINEAR", "CPU")
getImage()
Short description

Get the image at the specified pyramid level. 0 is the 'finest' level i.e. the original image. The return image is a deep copy of the level image

Parameters
Name Type Description

pyramidImage

CONST_OBJECT Image.Pyramid

The image pyramid.

level

INT

The pyramid level to grab the image from.

Return values
Name Type Description

image

OBJECT Image

The image at the specified pyramid level.

Sample
image = Image.Pyramid.getImage(pyramidImage, levelCount)
getLevelCount()
Short description

Get the number of pyramid levels.

Parameters
Name Type Description

pyramidImage

CONST_OBJECT Image.Pyramid

The image pyramid.

Return values
Name Type Description

levelCount

INT

The number of pyramid levels.

Sample
levelCount = Image.Pyramid.getLevelCount(pyramidImage)
getProcessingUnit()
Short description

Get configured processing unit.

Parameters
Name Type Description

pyramidImage

OBJECT Image.Pyramid

The image pyramid.

Return values
Name Type Description

processingUnit

ENUM ProcessingUnit

Processing Unit to use (CPU, FPGA).

Sample
processingUnit = Image.Pyramid.getProcessingUnit(pyramidImage)
resize()
Short description

Resizes an existing image pyramid in terms of the number of pyramid levels, i.e., the pyramid is extendend with more levels or levels are removed. The pyramid is updated inplace.

Keywords

cut, remove, extend

Parameters
Name Type Description

pyramidImage

OBJECT Image.Pyramid

The image pyramid.

levelCount

INT

The new number of pyramid levels. One level will be used for the original image, so to get at least one downscaled version the levelCount parameter must be larger than 1. Note that the created ImagePyramid may contain fewer levels as the coarsest level is limited to a side of max 16 pixels.

Return values
Name Type Description

pyramidImage

OBJECT Image.Pyramid

Reference to the resized pyramid, or nil if something goes wrong. Note that the function works inplace, modifying the object directly, the output is mainly for error checking.

Sample
pyramidImage = Image.Pyramid.resize(pyramidImage, levelCount)
setProcessingUnit()
Short description

Set processing unit to use for pyramid generation.

Parameters
Name Type Description

pyramidImage

OBJECT Image.Pyramid

The image pyramid.

processingUnit

ENUM ProcessingUnit

Processing Unit to use (CPU, FPGA).

Return values
Name Type Description

success

BOOL

True if set was successful.

Sample
success = Image.Pyramid.setProcessingUnit(pyramidImage, "CPU")
toString()
Short description

Get a brief string description of the image pyramid. This is equal to the text shown in the debugger to describe the image pyramid.

Parameters
Name Type Description

pyramidImage

CONST_OBJECT Image.Pyramid

The image pyramid.

Return values
Name Type Description

string

STRING

Description of the image pyramid

Sample
print("Description: " .. Image.Pyramid.toString(pyramidImage))

Image.ShapeFitter

Short description

This is a tool for fitting geometrical object like lines, circles and ellipses to edges and contours in an image. For grayscale images, the geometrical objects are fitted to transitions between dark and bright image contents. For heightmaps, they are fitted to transitions between low and high z values. To get started, create a ShapeFitter with the create function and then call fitLine, fitCircle or fitEllipse to adjust a line, circle or ellipse to fit to the image data. These are primarily intended for intensity images, however images with missing data are supported. For height maps, the function fitLine3D fits a 3D line to edges in the height map. For more detailed control of the fitting behavior, call the set functions before calling the fit function. The shape fitting procedure consists of the following steps: - A number of probe lines are created along the search region. An edge point is found on each probe line. - The geometrical object that best fits to the detected edge points is returned.

Keywords

RANSAC, contour, edges, least squares, model, fitting

Functions

create()
Short description

Create a shape fitter with default settings.

Return values
Name Type Description

shapeFitter

HANDLE

Created shape fitter.

Sample
shapeFitter = Image.ShapeFitter.create()
fitArc()
Short description

Fit a circular arc using the current settings within a search region defined by a shape sector. The angular extent of the fitted arc is copied from the search sector. Image world coordinate system handling: The arc is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the arc is only fitted to valid data.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

image

CONST_OBJECT Image

Input image.

searchSector

CONST_OBJECT Shape

Search region, defining the search region center, inner and outer radii, and the angles that limit the sector.

Return values
Name Type Description

arc

OBJECT Shape

Fitted arc.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final circle and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample
arc, quality = Image.ShapeFitter.fitArc(shapeFitter, image, searchSector)
fitCircle()
Short description

Fit a circle using the current settings within a search region defined by two concentric circles. Image world coordinate system handling: The circle is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the circle is only fitted to valid data.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

image

CONST_OBJECT Image

Input image.

outerCircle

CONST_OBJECT Shape

Outer circle of the search region, defining the search region center and outer radius of the search region.

innerRadius

FLOAT

Inner radius of the search region.

Return values
Name Type Description

circle

OBJECT Shape

Fitted circle.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final circle and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample
circle, quality = Image.ShapeFitter.fitCircle(shapeFitter, image, outerCircle, innerRadius)
fitCircle3D()
Short description

Fit a circle in 3D using the current settings. In addition to the xy-region defined by the outerCircle and the innerRadius, the zBounds parameter allows limiting the edge point search space in height. Image world coordinate system handling: The circle is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the circle is only fitted to valid data.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

image

CONST_OBJECT Image

Input image.

outerCircle

CONST_OBJECT Shape

Outer circle of the search region, defining the search region center and outer radius of the search region.

innerRadius

FLOAT

Inner radius of the search region.

zBounds

FLOAT

Two values providing the min and max z values where edges are searched for.

Return values
Name Type Description

circle

OBJECT Shape3D

Fitted circle.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final line and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample
circle, quality = Image.ShapeFitter.fitCircle3D(shapeFitter, image, outerCircle, innerRadius, zBounds
fitEllipse()
Short description

Fit an ellipse using the current settings within a search region defined by two concentric circles. For ellipse fitting, least squares methods are very sensitive to noise. Using the ransac method is highly recommended. Image world coordinate system handling: The ellipse is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the ellipse is only fitted to valid data.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

image

CONST_OBJECT Image

Input image.

outerCircle

CONST_OBJECT Shape

Outer circle of the search region, defining the search region center and outer radius of the search region.

innerRadius

FLOAT

Inner radius of the search region.

Return values
Name Type Description

ellipse

OBJECT Shape

Fitted ellipse, or nil on failure.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final ellipse and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample
ellipse, quality = Image.ShapeFitter.fitEllipse(shapeFitter, image, outerCircle, innerRadius)
fitLine()
Short description

Fit a line using the current settings. The direction parameter specifies the direction of the probe lines, and should be an angle in radians pointing across the edge. - If direction = 0, the probes are oriented left-to-right (expecting to cross the edge when moving left-to-right in the image). - If direction = PI/2, the probes are oriented top-to-bottom (expecting to cross the edge when moving top-to-bottom in the image). Image world coordinate system handling: The line is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the line is only fitted to valid data.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

image

CONST_OBJECT Image

Input image.

region

CONST_OBJECT Image.PixelRegion

Input region.

direction

FLOAT

Approximate edge direction in radians, defines the direction of the edge probes.

Return values
Name Type Description

lineSeg

OBJECT Shape

Fitted line segment or nil on failure.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final line and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample
lineSeg, quality = Image.ShapeFitter.fitLine(shapeFitter, image, region, direction)
fitLine3D()
Short description

Fit a 3D line using the current settings. In addition to the xy-region defined by the PixelRegion parameter, the zBounds parameter allows limiting the edge point search space in height. The direction parameter specifies the direction of the probe lines, and should be an angle in radians pointing across the edge. - If direction = 0, the probes are oriented left-to-right (expecting to cross the edge when moving left-to-right in the image). - If direction = PI/2, the probes are oriented top-to-bottom (expecting to cross the edge when moving top-to-bottom in the image). Image world coordinate system handling: The line is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the line is only fitted to valid data.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

image

CONST_OBJECT Image

Input image.

region

CONST_OBJECT Image.PixelRegion

Input region, defines an area in xy-space.

zBounds

FLOAT

Two values providing the min and max z values where edges are searched for.

direction

FLOAT

Approximate edge direction in radians, defines the direction of the edge probes.

Return values
Name Type Description

lineSegment

OBJECT Shape3D

The fitted line segment or nil on failure.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final line and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%.

Sample
lineSegment, quality = Image.ShapeFitter.fitLine3D(shapeFitter, image, region, zBounds, direction)
getEdgePoints()
Short description

Get the edge points used in the last call to any of the 2D fit functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final shape. The second list contains all points that were extracted but not used for fitting the shape. For the least squares method, all points are always in the first list. Image world coordinate system handling: The points are returned in world coordinates. Missing data handling: Pixels with missing data are ignored, the edge points are only located on valid data.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

Return values
Name Type Description

inlierPoints

OBJECT Point

Points used for the final fitting of the shape, a subset of the detected points.

outlierPoints

OBJECT Point

Points not used for the final fitting, the remainder of the detected points.

Sample
inlierPoints, outlierPoints = Image.ShapeFitter.getEdgePoints(shapeFitter)
getEdgePoints3D()
Short description

Get the 3D edge points used in the last call to any of the 3D fit functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final shape. The second list contains all points that were extracted but not used for fitting the shape. For the least squares method, all points are always in the first list. Image world coordinate system handling: The points are returned in world coordinates. Missing data handling: Pixels with missing data are ignored, the edge points are only located on valid data.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

Return values
Name Type Description

inlierPoints

OBJECT Point

Points used for the final fitting of the shape, a subset of the detected points.

outlierPoints

OBJECT Point

Points not used for the final fitting, the remainder of the detected points.

Sample
points = Image.ShapeFitter.getEdgePoints3D(shapeFitter)
setDifferenceStep()
Short description

Controls the distance between the two points from which the edge height / strength is measured. Increasing this value can improve the accuracy for very blurred edges, where there is no sharp transition from dark to bright (or from low to high z value for height maps).

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

step

INT

Difference step in pixels, must be greater than or equal to 1. The default values is 2.

Sample
Image.ShapeFitter.setDifferenceStep(shapeFitter, 5)
setFitMode()
Short description

Set the geometrical fitting mode. The following modes are supported: - LEASTSQUARES uses all points. This is fast and easy, but can produce poor results if there are many spurious edge points nearby (default). When using this method, the inlier rate will always be 100%. - RANSAC is a robust method with outlier rejection. Using this method, spurious edge points can be ignored. This mode requires an outlier margin to be set by setOutlierMargin. The number of iterations can be set by setIterations. - TRIMMED is a two-stage least squares method, where points further away from the fitted shape in the first round than the outlier margin (set by setOutlierMargin) is removed before using least squares again to fit a new shape to the remaining points. This is faster than RANSAC but not as robust to outliers.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

fitMode

ENUM Shape.PointFitMode

Geometrical fitting mode to use. The default is LEASTSQUARES. For many applications this should be changed to RANSAC to be robust to outliers.

Sample
Image.ShapeFitter.setFitMode(shapeFitter, "RANSAC")
setInterpolation()
Short description

Set which interpolation method to use in the edge profiles. The default value, NEAREST, is often a good choice. Changing to LINEAR can give slightly better accuracy, but with additional computational cost.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

interpolation

ENUM InterpolationMethod

Interpolation method.

Sample
Image.ShapeFitter.setInterpolation(shapeFitter, "LINEAR")
setIterations()
Short description

Set the number of iterations in the point fitting step. Only used when setFitMode specifies a robust method like RANSAC. A higher value makes the method more robust, but consumes more computation time. The default is 100 iterations.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

iterations

INT

Number of iterations.

Sample
Image.ShapeFitter.setIterations(shapeFitter, 50)
setOutlierMargin()
Short description

Set the outlier margin in world units for the final geometrical fitting step. This parameter is not used for the default fitting method, least squares. The interpretation of the parameter depends on the fitting mode parameter: - ABSOLUTE: the outlier margin is defined in absolute world units (typically mm). Any points further away from the fitted geometrical object than this margin will be ignored. - RANK: the outlier margin is interpreted as a rank measure, defining the rate of points to include. In this case, the margin must be in the range (0.0, 1.0). A rank margin of 0.7 means that only the best fitting 70% of all points will be included, and the rest ignored. In general a larger value means that more points are included in the fitting, which can improve the accuracy as long as all included points are valid. A smaller value makes the algorithm reject more points, which can increases robustness against single erroneous points. The default is an ABSOLUTE margin of 1.0 world units. Image world coordinate system handling: The ABSOLUTE margin is expressed in world coordinate units.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

margin

FLOAT

Outlier margin, expressed in world coordinate units or as a rank measure, depending on the marginType.

marginType

ENUM Shape.OutlierMarginType

Outlier margin type. Default is ABSOLUTE.

Sample
Image.ShapeFitter.setOutlierMargin(shapeFitter, margin, marginType)
setPolarity()
Short description

Set the edge polarity that the shape fitter is looking for. This controls the kind of transition that the fitter will look for: - POSITIVE means dark-to-bright for grayscale images, and low-to-high for heightmaps. - NEGATIVE means bright-to-dark for grayscale images and high-to-low for heightmaps. - ANY means any of the above (default). This is related to the probe direction, which for line fitting is a parameter to fitLine. For circle and ellipse fitting, the probe direction is always from the center and out.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

polarity

ENUM Profile.SlopePolarity

Edge polarity.

Sample
Image.ShapeFitter.setPolarity(shapeFitter, "POSITIVE")
setProbeCount()
Short description

Set the edge probe count. A lower number reduces computation time but also reduces accuracy. If a very large number if specified, the number of probes is limited such that the spacing between probes is at most one pixel. Default: 100 probes.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

count

INT

Probe count. Must be >= 4.

Sample
Image.ShapeFitter.setProbeCount(shapeFitter, count)
setSelection()
Short description

Decide which edge point to select if there are several candidates available. The selection is related to the probe direction, which for line fitting is a parameter to fitLine. For circle and ellipse fitting, the probe direction is always from the center and out. If using FIRST or LAST, remember to set the edge threshold. - STRONGEST selects the strongest edge along the probe (default). - FIRST selects the first edge encountered along the probe. - LAST selects the last edge encountered along the probe.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

selection

ENUM EdgeSelection

Edge selection criteria.

Sample
Image.ShapeFitter.setSelection(shapeFitter, "FIRST")
setSide()
Short description

Decide which side of the edge to adjust to. This will adjust the edge points slightly towards the high or low side of the edge, or keep the edge at the center. - CENTER centers the point on the edge (default for intensity images). - HIGH selects the point on the high/bright side of the edge (default for height maps). - LOW selects the point on the low/dark side of the edge.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

side

ENUM Profile.EdgeSide

Edge side.

Sample
Image.ShapeFitter.setSide(shapeFitter, "HIGH")
setThreshold()
Short description

Set the edge threshold. For grayscale images, this can be interpreted as the required edge sharpness. For height maps, this can be interpreted as the edge step. A higher value means that only strong transitions are considered. The default value is 0, which only works well together with STRONGEST as edge selection criterion (see setSelection). If the selection criteria is FIRST or LAST, a threshold should be specified using this function. Image world coordinate system handling: The threshold is expressed in world coordinates, taking the pixel z-size into account.

Parameters
Name Type Description

shapeFitter

HANDLE

Shape fitter to use.

threshold

FLOAT

Threshold value. The default value is 0, which only works well together with STRONGEST as edge selection critetion in the setSelection function. Increase threshold for other setting of setSelection.

Sample
Image.ShapeFitter.setThreshold(shapeFitter, 10)

Image.SurfaceFitter

Short description

This is a tool for fitting geometrical 3D object like planes and rectangles to surfaces in range images. To get started, create a SurfaceFitter with the create function and then call fitPlane or fitRectangle to adjust a plane or rectangle to image data. For more detailed control of the fitting behavior, call the set functions before calling the fit function. The surface fitting procedure consists of the following steps: - The set of points corresponding to the pixels within the PixelRegion and z-value bounds is found. A 3D shape enclosing the desired part of the height map can be converted to a PixelRegion and z-bounds via Shape3D.toPixelRegion(). - The geometrical object that best fits the detected points is returned.

Keywords

RANSAC, least squares, model, fitting

Functions

create()
Short description

Create a surface fitter with default settings.

Return values
Name Type Description

surfaceFitter

HANDLE

Created surface fitter.

Sample
surfaceFitter = Image.SurfaceFitter.create()
fitPlane()
Short description

Fit a 3D plane to image height values within a specified region using the current fit mode. The distance along the z-direction from the height map entries to the plane is minimized. Image world coordinate system handling: The plane is fitted in world coordinates. Missing data handling: Pixels with missing data are disregarded, the plane is only fitted to valid data.

Parameters
Name Type Description

surfaceFitter

HANDLE

Surface fitter to use.

image

CONST_OBJECT Image

Input image.

region

CONST_OBJECT Image.PixelRegion

Input region indicating which area to fit to. Optional, the default is to use the entire image.

boundsZ

FLOAT

Lower and upper z-bound. Optional, the default is to use all points.

Return values
Name Type Description

plane

OBJECT Shape3D

The fitted plane.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the plane.

Sample
plane, quality = Image.SurfaceFitter.fitPlane(surfaceFitter, image, region, lowerBoundZ, upperBoundZ)
fitRectangle()
Short description

Fit a rectangle in 3D to image height values within a specified region using the current fit mode. Similar to fitPlane but the rectangle is limited to the extent of the fitted points. By default, the rectangle is rotated in-plane to find the minimal area rectangle enclosing the inlier points. The distance along the z-direction from the height map entries to the plane is minimized. Image world coordinate system handling: The rectangle is fitted in world coordinates. Missing data handling: Pixels with missing data are disregarded, the rectangle is only fitted to valid data.

Parameters
Name Type Description

surfaceFitter

HANDLE

Surface fitter to use.

image

CONST_OBJECT Image

Input image.

region

CONST_OBJECT Image.PixelRegion

Input region indicating which area to fit to. Optional, the default is to use the entire image.

boundsZ

FLOAT

Lower and upper z-bound. Optional, the default is to use all points.

oriented

BOOL

Flag controlling if the rectangle should be rotated to minimize rectangle area (default). If set to false, the in-plane rotation of the fitted rectangle is related to the coordinate axes.

Return values
Name Type Description

rectangle

OBJECT Shape3D

The fitted rectangle.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the rectangle.

Sample
rectangle, quality = Image.SurfaceFitter.fitRectangle(surfaceFitter, image, region, zBounds, oriented)
getSurfacePoints()
Short description

Get the 3D points used in the last call to any of the fit functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final shape. The second list contains all points that were extracted but not used for fitting the shape. For the least squares method, all points are always in the first list. The number of returned points is limited. If the total number of points exceeds the set limit, the last points are skipped. Image world coordinate system handling: The returned points are in world coordinates. Missing data handling: Pixels with missing data are disregarded.

Parameters
Name Type Description

surfaceFitter

HANDLE

Surface fitter to use.

pointCountLimit

INT

Limit the number of points returned. Optional, default is 50000 points maximum.

Return values
Name Type Description

inlierPoints

OBJECT Point

Points used for the final fitting of the shape, a subset of the detected points.

outlierPoints

OBJECT Point

Points not used for the final fitting, the remainder of the detected points.

Sample
inlierPoints, outlierPoints = Image.SurfaceFitter.getSurfacePoints(surfaceFitter)
setFitMode()
Short description

Set the geometrical fitting mode. The following modes are supported: - LEASTSQUARES includes all points. This is fast and easy, but can produce poor results if there are many spurious points nearby (default). - RANSAC is a robust method with outlier rejection. Using this method, spurious points can be ignored. This mode requires an outlier margin to be set by setOutlierMargin and uses the number of iterations set through setIterations. - TRIMMED is faster than ransac and more robust than least squares. It first fits a plane to all points using least squares. The points farther from the plane than set outlierMargin are removed and a new plane is fitted to the remaining points using least squares.

Parameters
Name Type Description

surfaceFitter

HANDLE

Surface fitter to use.

fitMode

ENUM Shape.PointFitMode

Geometrical fitting mode to use. The default is LEASTSQUARES. For many applications this should be changed to RANSAC to be robust to outliers.

Sample
Image.SurfaceFitter.setFitMode(surfaceFitter, fitMode)
setIterations()
Short description

Set the number of iterations in the point fitting step. Only used when setFitMode specifies a robust method like RANSAC. A higher value makes the method more robust, but consumes more computation time.

Parameters
Name Type Description

surfaceFitter

HANDLE

Surface fitter to use.

iterations

INT

Number of iterations. The default is 100 iterations.

Sample
Image.SurfaceFitter.setIterations(surfaceFitter, iterations)
setOutlierMargin()
Short description

Set the outlier margin for the final geometrical fitting step. The interpretation of the margin value depends on the margin type. For an ABSOLUTE margin, any points further away from the fitted geometrical object than this margin will be ignored. The RANK margin includes a given part of the point set, i.e. a rank margin of 0.7 will search for the best shape fitting 70% of the points. For both margin types, a large value means that more points are included in the fitting, which can improve the accuracy as long as all included points are valid. A smaller value makes the algorithm reject more points, which can increases robustness against single erroneous points. The default value is 1.0 world units. Image world coordinate system handling: The ABSOLUTE margin is in image world coordinates.

Parameters
Name Type Description

surfaceFitter

HANDLE

Surface fitter to use.

margin

FLOAT

Outlier margin, expressed in world coordinate unit or as a rank measure, depending on the marginType.

marginType

ENUM Shape.OutlierMarginType

Outlier margin type. Default is ABSOLUTE.

Sample
Image.SurfaceFitter.setOutlierMargin(surfaceFitter, margin, marginType)
setReductionFactor()
Short description

Allows for quick reduction of the number of points to fit a shape to for large surfaces. Every N:th pixel in every N:th row is used, reducing computation time. Setting this parameter to one (default) fits the shape to all pixels in the region. Setting this parameter to two, approximately one quarter of the pixels are used.

Parameters
Name Type Description

surfaceFitter

HANDLE

Surface fitter to use.

n

INT

Using every n:th pixel in every n:th row.

Sample
Image.SurfaceFitter.setReductionFactor(surfaceFitter, n)

LED

Short description

Access to the LEDs of the device to change their mode. Can be used to activate or deactivate LEDs. If LED support for colors might be possible, there is the function setColor which can be used to change the LED color.

Functions

activate()
Short description

Sets the LED to active. Some LEDs might deactivate theirself after a max. possible active time (e.g. 10 secs). This depends on the concrete LED.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the LED

activeTimeMs

INT

The time the LED is active. Per default stays active forever or might be deactivated after the max. possible active time of the LED (see concrete LED documentation)

Sample
LED.activate(handle)
Short description

Sets the LED to blinking mode so that it is automatically set to active and inactive for the specified times.

Parameters
Name Type Description

handle

HANDLE

Unique handle of the LED

pulsTimeMs

INT

The time the LED is active

pauseTimeMs

INT

The time the LED is inactive. If not specified, the pulseTimeMs is also used as pauseTimeMs.

Sample
LED.blink(handle, 600, 300)
create()
Short description

Creates a handle for the LED if exists and not already in use.

Parameters
Name Type Description

ledName

ENUM LEDs

The name of the LED to use

Return values
Name Type Description

handle

HANDLE

Unique handle for the LED. Nil if not available or already in use.

Sample
handle = LED.create("LED_1")
deactivate()
Short description

Sets the LED to inactive.

Parameters
Name Type Description

handle

HANDLE

Unique handle to the LED

Sample
LED.deactivate(handle)
setColor()
Short description

If the LED supports multiple colors it could be set here. If LED is already activated, the color is switched directly. Default is set all to full color (white or the only color the LED supports). The possible colors of the LED could be get known from the device manual.

Parameters
Name Type Description

handle

HANDLE

Unique handle of the LED

color

AUTO

Flexible parameter to set the color. Could be a name of a color, a single int RGB value (e.g. 0x123456) or a vector of three ints for each part of the RGB value.

Sample
by name: LED.setColor(handle, "red")
by RGB value: LED.setColor(handle, {255,0,0} )
by RGB state: LED.setColor(handle, {true,false,false} )

LUA.debug

Short description

This library provides the functionality of the debug interface (4.9) to Lua programs. You should exert care when using this library. Several of its functions violate basic assumptions about Lua code (e.g., that variables local to a function cannot be accessed from outside; that userdata metatables cannot be changed by Lua code; that Lua programs do not crash) and therefore can compromise otherwise secure code. Moreover, some functions in this library may be slow. All functions in this library are provided inside the debug table. All functions that operate over a thread have an optional first argument which is the thread to operate over. The default is always the current thread.

Functions

getinfo()
Short description

Returns a table with information about a function. You can give the function directly or you can give a number as the value of f, which means the function running at level f of the call stack of the given thread: level 0 is the current function (getinfo itself); level 1 is the function that called getinfo (except for tail calls, which do not count on the stack); and so on. If f is a number larger than the number of active functions, then getinfo returns nil. The returned table can contain all the fields returned by lua_getinfo, with the string what describing which fields to fill in. The default for what is to get all information available, except the table of valid lines. If present, the option 'f' adds a field named func with the function itself. If present, the option 'L' adds a field named activelines with the table of valid lines. For instance, the expression debug.getinfo(1,"n").name returns a name for the current function, if a reasonable name can be found, and the expression debug.getinfo(print) returns a table with all available information about the print function.

Parameters
Name Type Description

thread

AUTO

thread

f

AUTO

what

STRING

Return values
Name Type Description

table

AUTO

table

getlocal()
Short description

This function returns the name and the value of the local variable with index local of the function at level f of the stack. This function accesses not only explicit local variables, but also parameters, temporaries, etc. The first parameter or local variable has index 1, and so on, following the order that they are declared in the code, counting only the variables that are active in the current scope of the function. Negative indices refer to vararg parameters; -1 is the first vararg parameter. The function returns nil if there is no variable with the given index, and raises an error when called with a level out of range. (You can call debug.getinfo to check whether the level is valid.) Variable names starting with '(' (open parenthesis) represent variables with no known names (internal variables such as loop control variables, and variables from chunks saved without debug information). The parameter f may also be a function. In that case, getlocal returns only the name of function parameters.

Parameters
Name Type Description

thread

AUTO

thread

f

AUTO

local

INT

Return values
Name Type Description

name

STRING

value

AUTO

getmetatable()
Short description

Returns the metatable of the given value or nil if it does not have a metatable.

Parameters
Name Type Description

value

AUTO

Return values
Name Type Description

table

AUTO

table

getregistry()
Short description

Returns the registry table (see lua reference 4.5).

Return values
Name Type Description

table

AUTO

table

traceback()
Short description

If message is present but is neither a string nor nil, this function returns message without further processing. Otherwise, it returns a string with a traceback of the call stack. The optional message string is appended at the beginning of the traceback. An optional level number tells at which level to start the traceback (default is 1, the function calling traceback).

Parameters
Name Type Description

thread

AUTO

thread

message

STRING

level

INT

Return values
Name Type Description

message

STRING

LUA.math

Short description

This library provides basic mathematical functions. It provides all its functions and constants inside the table math. Functions with the annotation "integer/float" give integer results for integer arguments and float results for float (or mixed) arguments. Rounding functions (math.ceil, math.floor, and math.modf) return an integer when the result fits in the range of an integer, or a float otherwise.

Functions

abs()
Short description

Returns the absolute value of x. (integer/float)

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

abs

FLOAT

number

acos()
Short description

Returns the arc cosine of x (in radians).

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

acos

FLOAT

number

asin()
Short description

Returns the arc sine of x (in radians).

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

asin

FLOAT

number

atan()
Short description

Returns the arc tangent of y/x (in radians), but uses the signs of both parameters to find the quadrant of the result. (It also handles correctly the case of x being zero.) The default value for x is 1, so that the call math.atan(y) returns the arc tangent of y.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

atan

FLOAT

number

atan2()
Short description

DEPRECATED: Use "atan" instead with additional argument. Returns the arc tangent of y/x (in radians), but uses the signs of both parameters to find the quadrant of the result. (It also handles correctly the case of x being zero.)

Parameters
Name Type Description

y

FLOAT

number

x

FLOAT

number

Return values
Name Type Description

atan2

FLOAT

number

ceil()
Short description

Returns the smallest integral value larger than or equal to x.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

ceil

FLOAT

number

cos()
Short description

Returns the cosine of x (assumed to be in radians).

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

cos

FLOAT

number

cosh()
Short description

DEPRECATED: Use an external library or implement it in Lua. Returns the hyperbolic cosine of x.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

cosh

FLOAT

number

deg()
Short description

Returns the angle x (given in radians) in degrees.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

deg

FLOAT

number

exp()
Short description

Returns the value e^x (where e is the base of natural logarithms).

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

exp

FLOAT

number

floor()
Short description

Returns the largest integral value smaller than or equal to x.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

floor

FLOAT

number

fmod()
Short description

Returns the remainder of the division of x by y that rounds the quotient towards zero. (integer/float)

Parameters
Name Type Description

x

FLOAT

number

y

FLOAT

number

Return values
Name Type Description

fmod

FLOAT

number

frexp()
Short description

DEPRECATED: Use an external library or implement it in Lua. Returns m and e such that x = m2^e, e is an integer and the absolute value of m is in the range [0.5, 1) (or zero when x is zero).

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

m

FLOAT

number

e

FLOAT

number

ldexp()
Short description

DEPRECATED: Replace with "x*2.0^e". Returns m2^e (e should be an integer).

Parameters
Name Type Description

m

FLOAT

number

e

FLOAT

number

Return values
Name Type Description

ldexp

FLOAT

number

log()
Short description

Returns the logarithm of x in the given base. The default for base is e (so that the function returns the natural logarithm of x).

Parameters
Name Type Description

x

FLOAT

number

base

FLOAT

number

Return values
Name Type Description

log

FLOAT

number

log10()
Short description

DEPRECATED: Use "log" instead with additional argument. Returns the logarithm of x in base 10.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

log10

FLOAT

number

max()
Short description

Returns the argument with the maximum value, according to the Lua operator < (integer/float)

Parameters
Name Type Description

x1

FLOAT

number

x2

FLOAT

number

xN

FLOAT

number

Return values
Name Type Description

max

FLOAT

number

min()
Short description

Returns the argument with the minimum value, according to the Lua operator >. (integer/float)

Parameters
Name Type Description

x1

FLOAT

number

x2

FLOAT

number

xN

FLOAT

number

Return values
Name Type Description

min

FLOAT

number

modf()
Short description

Returns the integral part of x and the fractional part of x. Its second result is always a float.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

integral

FLOAT

number

fractional

FLOAT

number

pow()
Short description

DEPRECATED: Replace with "x^y". Returns x^y. (You can also use the expression x^y to compute this value.)

Parameters
Name Type Description

x

FLOAT

number

y

FLOAT

number

Return values
Name Type Description

pow

FLOAT

number

rad()
Short description

Returns the angle x (given in degrees) in radians.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

rad

FLOAT

number

random()
Short description

When called without arguments, returns a pseudo-random float with uniform distribution in the range [0,1). When called with two integers m and n, math.random returns a pseudo-random integer with uniform distribution in the range [m, n]. (The value n-m cannot be negative and must fit in a Lua integer.) The call math.random(n) is equivalent to math.random(1,n). This function is an interface to the underling pseudo-random generator function provided by C.

Parameters
Name Type Description

m

FLOAT

number

n

FLOAT

number

Return values
Name Type Description

random

FLOAT

number

randomseed()
Short description

Sets x as the "seed" for the pseudo-random generator: equal seeds produce equal sequences of numbers.

Parameters
Name Type Description

x

FLOAT

number

sin()
Short description

Returns the sine of x (assumed to be in radians).

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

sin

FLOAT

number

sinh()
Short description

DEPRECATED: Use an external library or implement it in Lua. Returns the hyperbolic sine of x.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

sinh

FLOAT

number

sqrt()
Short description

Returns the square root of x. (You can also use the expression x^0.5 to compute this value.)

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

sqrt

FLOAT

number

tan()
Short description

Returns the tangent of x (assumed to be in radians).

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

tan

FLOAT

number

tanh()
Short description

DEPRECATED: Use an external library or implement it in Lua. Returns the hyperbolic tangent of x.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

tanh

FLOAT

number

tointeger()
Short description

If the value x is convertible to an integer, returns that integer. Otherwise, returns nil.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

integer

INT

type()
Short description

Returns "integer" if x is an integer, "float" if it is a float, or nil if x is not a number.

Parameters
Name Type Description

x

FLOAT

number

Return values
Name Type Description

type

STRING

ult()
Short description

Returns a boolean, true if integer m is below integer n when they are compared as unsigned integers.

Parameters
Name Type Description

m

INT

n

INT

Return values
Name Type Description

ult

BOOL

LUA.string

Short description

This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string. Thus, the last character is at position -1, and so on. The string library provides all its functions inside the table string. It also sets a metatable for strings where the __index field points to the string table. Therefore, you can use the string functions in object-oriented style. For instance, string.byte(s,i) can be written as s:byte(i). The string library assumes one-byte character encodings. 6.4.1 - Patterns Patterns in Lua are described by regular strings, which are interpreted as patterns by the pattern-matching functions string.find, string.gmatch, string.gsub, and string.match. This section describes the syntax and the meaning (that is, what they match) of these strings. Character Class: A character class is used to represent a set of characters. The following combinations are allowed in describing a character class: x: (where x is not one of the magic characters ^$()%.[]-?) represents the character x itself. .: (a dot) represents all characters. %a: represents all letters. %c: represents all control characters. %d: represents all digits. %g: represents all printable characters except space. %l: represents all lowercase letters. %p: represents all punctuation characters. %s: represents all space characters. %u: represents all uppercase letters. %w: represents all alphanumeric characters. %x: represents all hexadecimal digits. %x: (where x is any non-alphanumeric character) represents the character x. This is the standard way to escape the magic characters. Any non-alphanumeric character (including all punctuation characters, even the non-magical) can be preceded by a '%' when used to represent itself in a pattern. [set]: represents the class which is the union of all characters in set. A range of characters can be specified by separating the end characters of the range, in ascending order, with a '-'. All classes %x described above can also be used as components in set. All other characters in set represent themselves. For example, [%w_] (or [_%w]) represents all alphanumeric characters plus the underscore, [0-7] represents the octal digits, and [0-7%l%-] represents the octal digits plus the lowercase letters plus the '-' character. The interaction between ranges and classes is not defined. Therefore, patterns like [%a-z] or [a-%%] have no meaning. [^set]: represents the complement of set, where set is interpreted as above. For all classes represented by single letters (%a, %c, etc.), the corresponding uppercase letter represents the complement of the class. For instance, %S represents all non-space characters. The definitions of letter, space, and other character groups depend on the current locale. In particular, the class [a-z] may not be equivalent to %l. Pattern Item: A pattern item can be a single character class, which matches any single character in the class; a single character class followed by '*', which matches zero or more repetitions of characters in the class. These repetition items will always match the longest possible sequence; a single character class followed by '', which matches one or more repetitions of characters in the class. These repetition items will always match the longest possible sequence; a single character class followed by '-', which also matches zero or more repetitions of characters in the class. Unlike '', these repetition items will always match the shortest possible sequence; a single character class followed by '?', which matches zero or one occurrence of a character in the class. It always matches one occurrence if possible; %n, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below); %bxy, where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item %b() matches expressions with balanced parentheses. %f[set], a frontier pattern; such item matches an empty string at any position such that the next character belongs to set and the previous character does not belong to set. The set set is interpreted as previously described. The beginning and the end of the subject are handled as if they were the character '\0'. Pattern: A pattern is a sequence of pattern items. A caret '^' at the beginning of a pattern anchors the match at the beginning of the subject string. A '$' at the end of a pattern anchors the match at the end of the subject string. At other positions, '^' and '$' have no special meaning and represent themselves. Captures: A pattern can contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use. Captures are numbered according to their left parentheses. For instance, in the pattern "(a*(.)%w(%s*))", the part of the string matching "a*(.)%w(%s*)" is stored as the first capture (and therefore has number 1); the character matching "." is captured with number 2, and the part matching "%s*" has number 3. As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5. 6.4.2 - Format Strings for Pack and Unpack The first argument to string.pack, string.packsize, and string.unpack is a format string, which describes the layout of the structure being created or read. A format string is a sequence of conversion options. The conversion options are as follows: <: sets little endian >: sets big endian =: sets native endian ![n]: sets maximum alignment to n (default is native alignment) b: a signed byte (char) B: an unsigned byte (char) h: a signed short (native size) H: an unsigned short (native size) l: a signed long (native size) L: an unsigned long (native size) j: a lua_Integer J: a lua_Unsigned T: a size_t (native size) i[n]: a signed int with n bytes (default is native size) I[n]: an unsigned int with n bytes (default is native size) f: a float (native size) d: a double (native size) n: a lua_Number cn: a fixed-sized string with n bytes z: a zero-terminated string s[n]: a string preceded by its length coded as an unsigned integer with n bytes (default is a size_t) x: one byte of padding Xop: an empty item that aligns according to option op (which is otherwise ignored) ' ': (empty space) ignored (A "[n]" means an optional integral numeral.) Except for padding, spaces, and configurations (options "xX <⇒!"), each option corresponds to an argument (in string.pack) or a result (in string.unpack). For options "!n", "sn", "in", and "In", n can be any integer between 1 and 16. All integral options check overflows; string.pack checks whether the given value fits in the given size; string.unpack checks whether the read value fits in a Lua integer. Any format string starts as if prefixed by "!1=", that is, with maximum alignment of 1 (no alignment) and native endianness. Alignment works as follows: For each option, the format gets extra padding until the data starts at an offset that is a multiple of the minimum between the option size and the maximum alignment; this minimum must be a power of 2. Options "c" and "z" are not aligned; option "s" follows the alignment of its starting integer. All padding is filled with zeros by string.pack (and ignored by string.unpack).

Functions

byte()
Short description

Returns the internal numeric codes of the characters s[i], s[i+1], …​, s[j]. The default value for i is 1; the default value for j is i. These indices are corrected following the same rules of function string.sub. Numeric codes are not necessarily portable across platforms.

Parameters
Name Type Description

s

STRING

i

INT

j

INT

Return values
Name Type Description

byte

INT

char()
Short description

Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numeric code equal to its corresponding argument. Numeric codes are not necessarily portable across platforms.

Parameters
Name Type Description

x1

INT

xN

INT

Return values
Name Type Description

string

STRING

dump()
Short description

Returns a string containing a binary representation (a binary chunk) of the given function, so that a later load on this string returns a copy of the function (but with new upvalues). If strip is a true value, the binary representation may not include all debug information about the function, to save space. Functions with upvalues have only their number of upvalues saved. When (re)loaded, those upvalues receive fresh instances containing nil. (You can use the debug library to serialize and reload the upvalues of a function in a way adequate to your needs.)

Parameters
Name Type Description

function

AUTO

function

Return values
Name Type Description

binary

BINARY

find()
Short description

Looks for the first match of pattern (see 6.4.1) in the string s. If it finds a match, then find returns the indices of s where this occurrence starts and ends; otherwise, it returns nil. A third, optional numeric argument init specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered magic. Note that if plain is given, then init must be given as well. If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.

Parameters
Name Type Description

s

STRING

pattern

STRING

init

INT

plain

BOOL

Return values
Name Type Description

x1

STRING

xN

STRING

format()
Short description

Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the ISO C function sprintf. The only differences are that the options/modifiers *, h, L, l, n, and p are not supported and that there is an extra option, q. The q option formats a string between double quotes, using escape sequences when necessary to ensure that it can safely be read back by the Lua interpreter. For instance, the call string.format('%q', 'a string with "quotes" and \n new line') may produce the string: "a string with \"quotes\" and \ new line" Options A, a, E, e, f, G, and g all expect a number as argument. Options c, d, i, o, u, X, and x expect an integer. Option q expects a string. Option s expects a string; if its argument is not a string, it is converted to one following the same rules of tostring. If the option has any modifier (flags, width, length), the string argument should not contain embedded zeros. When Lua is compiled with a non-C99 compiler, options A and a (hexadecimal floats) do not support any modifier (flags, width, length).

Parameters
Name Type Description

formatstring

STRING

x1

AUTO

xN

AUTO

gmatch()
Short description

Returns an iterator function that, each time it is called, returns the next captures from pattern (see 6.4.1) over the string s. If pattern specifies no captures, then the whole match is produced in each call. As an example, the following loop will iterate over all the words from string s, printing one per line: s = "hello world from Lua" for w in string.gmatch(s, "%a+") do print(w) end The next example collects all pairs key=value from the given string into a table: t = {} s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do t[k] = v end For this function, a caret '^' at the start of a pattern does not work as an anchor, as this would prevent the iteration.

Parameters
Name Type Description

s

STRING

pattern

STRING

Return values
Name Type Description

function

AUTO

function

gsub()
Short description

Returns a copy of s in which all (or the first n, if given) occurrences of the pattern (see 6.4.1) have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred. The name gsub comes from Global SUBstitution. If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %d, with d between 1 and 9, stands for the value of the d-th captured substring. The sequence %0 stands for the whole match. The sequence %% stands for a single %. If repl is a table, then the table is queried for every match, using the first capture as the key. If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order. In any case, if the pattern specifies no captures, then it behaves as if the whole pattern was inside a capture. If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string). Here are some examples: x = string.gsub("hello world", "(%w+)", "%1 %1") -→ x="hello hello world world" x = string.gsub("hello world", "%w+", "%0 %0", 1) -→ x="hello hello world" x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") -→ x="world hello Lua from" x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) -→ x="home = /home/roberto, user = roberto" x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) return load(s)() end) -→ x="4+5 = 9" local t = {name="lua", version="5.3"} x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) -→ x="lua-5.3.tar.gz"

Parameters
Name Type Description

s

STRING

pattern

STRING

repl

AUTO

n

AUTO

number

Return values
Name Type Description

copyS

STRING

numberOfMatches

INT

len()
Short description

Receives a string and returns its length. The empty string "" has length 0. Embedded zeros are counted, so "a\000bc\000" has length 5.

Parameters
Name Type Description

s

STRING

Return values
Name Type Description

len

INT

lower()
Short description

Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.

Parameters
Name Type Description

s

STRING

Return values
Name Type Description

string

STRING

match()
Short description

Looks for the first match of pattern in the string s. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative.

Parameters
Name Type Description

s

STRING

pattern

STRING

init

INT

Return values
Name Type Description

string

STRING

pack()
Short description

Returns a binary string containing the values v1, v2, etc. packed (that is, serialized in binary form) according to the format string fmt (see string description).

Parameters
Name Type Description

fmt

STRING

v1

AUTO

vN

AUTO

Return values
Name Type Description

binaryString

STRING

packsize()
Short description

Returns the size of a string resulting from string.pack with the given format. The format string cannot have the variable-length options 's' or 'z' (see 6.4.2).

Parameters
Name Type Description

fmt

STRING

Return values
Name Type Description

packsize

INT

rep()
Short description

Returns a string that is the concatenation of n copies of the string s separated by the string sep. The default value for sep is the empty string (that is, no separator). Returns the empty string if n is not positive. (Note that it is very easy to exhaust the memory of your machine with a single call to this function.)

Parameters
Name Type Description

s

STRING

n

INT

sep

STRING

Return values
Name Type Description

string

STRING

reverse()
Short description

Returns a string that is the string s reversed.

Parameters
Name Type Description

s

STRING

Return values
Name Type Description

string

STRING

sub()
Short description

Returns the substring of s that starts at i and continues until j; i and j can be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(s,1,j) returns a prefix of s with length j, and string.sub(s, -i) returns a suffix of s with length i. If, after the translation of negative indices, i is less than 1, it is corrected to 1. If j is greater than the string length, it is corrected to that length. If, after these corrections, i is greater than j, the function returns the empty string.

Parameters
Name Type Description

s

STRING

i

INT

j

INT

Return values
Name Type Description

substring

STRING

unpack()
Short description

Returns the values packed in string s (see string.pack) according to the format string fmt (see 6.4.2). An optional pos marks where to start reading in s (default is 1). After the read values, this function also returns the index of the first unread byte in s.

Parameters
Name Type Description

fmt

STRING

s

STRING

pos

INT

v1

AUTO

v2

AUTO

vN

AUTO

firstUnreadByte

INT

upper()
Short description

Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.

Parameters
Name Type Description

s

STRING

Return values
Name Type Description

string

STRING

LUA.table

Short description

This library provides generic functions for table manipulation. It provides all its functions inside the table table. Remember that, whenever an operation needs the length of a table, the table must be a proper sequence or have a __len metamethod (see 3.4.7). All functions ignore non-numeric keys in the tables given as arguments.

Functions

concat()
Short description

Given a list where all elements are strings or numbers, returns the string list[i]..sep..list[i+1] …​ sep..list[j]. The default value for sep is the empty string, the default for i is 1, and the default for j is ##list. If i is greater than j, returns the empty string.

Parameters
Name Type Description

list

AUTO

table

sep

STRING

i

INT

j

INT

Return values
Name Type Description

concat

STRING

insert()
Short description

Inserts element value at position pos in list, shifting up the elements list[pos], list[pos+1], …​, list[list]. The default value for pos is list+1, so that a call table.insert(t,x) inserts x at the end of list t.

Parameters
Name Type Description

list

AUTO

table

pos

INT

value

AUTO

move()
Short description

Moves elements from table a1 to table a2. This function performs the equivalent to the following multiple assignment: a2[t],…​ = a1[f],…​,a1[e]. The default for a2 is a1. The destination range can overlap with the source range. The number of elements to be moved must fit in a Lua integer.

Parameters
Name Type Description

a1

AUTO

table

f

INT

e

INT

t

INT

a2

AUTO

table

pack()
Short description

Returns a new table with all parameters stored into keys 1, 2, etc. and with a field "n" with the total number of parameters. Note that the resulting table may not be a sequence.

Parameters
Name Type Description

x1

AUTO

xN

AUTO

Return values
Name Type Description

table

AUTO

table

remove()
Short description

Removes from list the element at position pos, returning the value of the removed element. When pos is an integer between 1 and list, it shifts down the elements list[pos+1], list[pos+2], …​, list[list] and erases element list[list]; The index pos can also be 0 when list is 0, or list + 1; in those cases, the function erases the element list[pos]. The default value for pos is list, so that a call table.remove(l) removes the last element of list l.

Parameters
Name Type Description

list

AUTO

table

pos

INT

sort()
Short description

Sorts list elements in a given order, in-place, from list[1] to list[##list]. If comp is given, then it must be a function that receives two list elements and returns true when the first element must come before the second in the final order (so that, after the sort, i < j implies not comp(list[j],list[i])). If comp is not given, then the standard Lua operator > is used instead. Note that the comp function must define a strict partial order over the elements in the list; that is, it must be asymmetric and transitive. Otherwise, no valid sort may be possible. The sort algorithm is not stable; that is, elements not comparable by the given order (e.g., equal elements) may have their relative positions changed by the sort.

Parameters
Name Type Description

list

AUTO

table

comp

AUTO

function

unpack()
Short description

Returns the elements from the given list. This function is equivalent to return list[i], list[i+1], …​, list[j] By default, i is 1 and j is ##list.

Parameters
Name Type Description

list

AUTO

table

Return values
Name Type Description

x1

AUTO

xN

AUTO

LUA.utf8

Short description

This library provides basic support for UTF-8 encoding. It provides all its functions inside the table utf8. This library does not provide any support for Unicode other than the handling of the encoding. Any operation that needs the meaning of a character, such as character classification, is outside its scope. Unless stated otherwise, all functions that expect a byte position as a parameter assume that the given position is either the start of a byte sequence or one plus the length of the subject string. As in the string library, negative indices count from the end of the string.

Functions

char()
Short description

Receives zero or more integers, converts each one to its corresponding UTF-8 byte sequence and returns a string with the concatenation of all these sequences.

Parameters
Name Type Description

x1

INT

xN

INT

Return values
Name Type Description

string

STRING

codepoint()
Short description

Returns the codepoints (as integers) from all characters in s that start between byte position i and j (both included). The default for i is 1 and for j is i. It raises an error if it meets any invalid byte sequence.

Parameters
Name Type Description

s

STRING

i

INT

j

INT

Return values
Name Type Description

c

INT

codes()
Short description

Returns values so that the construction for p, c in utf8.codes(s) do body end will iterate over all characters in string s, with p being the position (in bytes) and c the code point of each character. It raises an error if it meets any invalid byte sequence.

Parameters
Name Type Description

s

STRING

Return values
Name Type Description

p

INT

c

INT

len()
Short description

Returns the number of UTF-8 characters in string s that start between positions i and j (both inclusive). The default for i is 1 and for j is -1. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte.

Parameters
Name Type Description

s

STRING

i

INT

j

INT

Return values
Name Type Description

len

INT

offset()
Short description

Returns the position (in bytes) where the encoding of the n-th character of s (counting from position i) starts. A negative n gets characters before position i. The default for i is 1 when n is non-negative and ##s + 1 otherwise, so that utf8.offset(s, -n) gets the offset of the n-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns nil. As a special case, when n is 0 the function returns the start of the encoding of the character that contains the i-th byte of s. This function assumes that s is a valid UTF-8 string.

Parameters
Name Type Description

s

STRING

n

INT

i

INT

Return values
Name Type Description

offset

INT

Log

Short description

Provides logging capabilities for Apps.

Functions

fine()
Short description

Logs a message with level "FINE"

Parameters
Name Type Description

msg

STRING

The message to print out

Sample
Log.fine("My message")
finer()
Short description

Logs a message with level "FINER"

Parameters
Name Type Description

msg

STRING

The message to print out

Sample
Log.finer("My message")
finest()
Short description

Logs a message with level "FINEST"

Parameters
Name Type Description

msg

STRING

The message to print out

Sample
Log.finest("My message")
info()
Short description

Logs a message with level "INFO"

Parameters
Name Type Description

msg

STRING

The message to print out

Sample
Log.info("My message")
isLogable()
Short description

Returns true if the logging on the specified level is enabled. This is useful to don’t create big log outputs if the logging is disabled and log output would not be used. Only interesting for log levels smaller than warning, because warning and severe output always is needed.

Parameters
Name Type Description

level

ENUM Level

The level

Return values
Name Type Description

isLogable

BOOL

True if the logging on the specified level is enabled

setConsoleMode()
Short description

Sets the logging handling to console mode (=default). This overwrites all other modes; only one mode can be assigned to the App’s logger.

Sample
Log.setConsoleMode()
setFileMode()
Short description

Sets the logging handling to file mode. This overwrites all other modes; only one mode can be assigned to the App’s logger. The writing of the logs to the logfile is done asynchronously in the background. The maximum number of logs in the queue for writing to file is 128 for each app. If the log queue is full, the new log is thrown away. The logfile will contain a "Some log messages were lost"-string if this happened. In this case the rate of log production has to be reduced by the app. When the maximum file size is reached, the file is divided into two halves: The first half(old entries) is discarded, the second half is shifted to the beginning of the file, so new log entries can be appended at the end. Note that it depends on the underlying operating system if the logged file can be accessed while it is written. If you want to open the logged file for reading, set the logger to another file or to another mode first. Accessing files is restricted to the public/ or private/ folder, so you may only use file paths starting with either public/ or private/.

Parameters
Name Type Description

fileName

STRING

File name inside the public or private folder

maxFileSize

INT

Maximum file size in range of 1024 (1 kB) to 104857600 (100 MB)

Return values
Name Type Description

success

BOOL

true when setting was successful

Sample
Log.setFileMode("private/log.txt", 1048576)
setLevel()
Short description

Sets the logging level for the current App

Parameters
Name Type Description

level

ENUM Level

The level

Sample
Log.setLevel("INFO")
severe()
Short description

Logs a message with level "SEVERE"

Parameters
Name Type Description

msg

STRING

The message to print out

Sample
Log.severe("My message")
warning()
Short description

Logs a message with level "WARNING"

Parameters
Name Type Description

msg

STRING

The message to print out

Sample
Log.warning("My message")

Log.Handler

Short description

Handlers are used to connect one or more loggers to one or more endpoints, the so-called 'sinks'. A sink can be either a file, a callback function or the AppStudio console. Every handler can be attached to an arbitrary number of loggers (local, shared or the engine logger) and an arbitrary number of sinks. However, there is only one global engine logger and only one console sink because AppStudio does not offer multiple consoles. To apply the configuration on a handler, the applyConfig() function must be called. It must also be called after making changes to an already installed handler, e.g. when changing the log level. You can also add callback sinks which use callback functions with the following signature: function myHandlerFunction(message, path, level, timestamp, appName, appPosition, sourceApi) print(message) end The parameters appName, appPosition and sourceApi contain the name of the app, file and line position in the app source code and the name of the API the log was sent from. If this information is not available, the corresponding strings are empty. handler = Log.Handler.create() handler:attachToLogger("App1.myLogger") handler:attachToSharedLogger("mySharedLogger") handler:addFileSink("private/log.txt", 1000000) handler:addCallbackSink("myHandlerFunction") handler:setConsoleSinkEnabled(true) handler:setLevel("WARNING") handler:applyConfig()

Functions

addCallbackSink()
Short description

Adds a callback sink to the handler. The signature is as follows: function myHandlerFunction(message, path, level, timestamp, appName, appPosition, sourceApi) print(message) end The parameters appName, appPosition and sourceApi contain the name of the app, file and line position in the app source code and the name of the API the log was sent from. If this information is not available, the corresponding strings are empty.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

callback

STRING

The callback to be triggered when a message is dispatched

Sample
function myHandlerFunction(message, path, level, timestamp, appName, appPosition, sourceApi)
  print(message)
end
Log.Handler.addCallbackSink(handle, "myHandlerFunction")
addFileSink()
Short description

Adds a file sink to the handler.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

filePath

STRING

Path to the log file

fileSize

INT

Maximum size of the log file before truncating. Has to be in the range [1024,104857600].

Return values
Name Type Description

success

BOOL

True if file sink was added, false if an error occurred

Sample
Log.Handler.addFileSink(handle, "private/my.log", 1000000)
applyConfig()
Short description

Applies the handle config. This must be called in order to install the low-level handlers with the configuration set on the handle. You must also call it to update the handler after changing settings.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

Sample
Log.Handler.applyConfig(handle)
attachToEngineLogger()
Short description

Attaches handler to the engine logger.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

Sample
Log.Handler.attachToEngineLogger(handle)
attachToLogger()
Short description

Attaches handler to an app-local logger.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

appPath

STRING

Path of the app logger in the form AppName.LocalLoggerName

Sample
Log.Handler.attachToLogger(handle, "AppName.LoggerName")
attachToSharedLogger()
Short description

Attaches handler to a shared logger.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

loggerName

STRING

Name of the logger

Sample
Log.Handler.attachToSharedLogger(handle, "LoggerName")
create()
Short description

Creates a new Log.Handler instance.

Return values
Name Type Description

handle

HANDLE

The new instance

Sample
local handle = Log.Handler.create()
setConsoleSinkEnabled()
Short description

Enables/disables forwarding to AppStudio console.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

enabled

BOOL

True to enable forwarding to AppStudio console, false to disable

Sample
Log.Handler.setConsoleSinkEnabled(handle, true)
setLevel()
Short description

Sets the logging level of the handler.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

level

ENUM Level

Log level

Sample
Log.Handler.setLevel(handle, WARNING)

Log.Logger

Short description

App-local logger which belongs to the app that creates it. Messages can be logged to the logger by using the functions named after the log levels (info, warning, severe, …​). To get output from the logger, a handler must be attached to it and connected to a sink. See Log.Handler for more information. logger = Log.Logger.create("myLogger") logger:warning("This is a warning")

Functions

create()
Short description

Creates a new Log.Logger instance.

Parameters
Name Type Description

loggerName

STRING

Name of the logger

Return values
Name Type Description

handle

HANDLE

The new instance

Sample
local handle = Log.Logger.create("loggerName")
fine()
Short description

Logs a message with level "FINE"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.Logger.fine(handle, "My message")
finer()
Short description

Logs a message with level "FINER"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.Logger.finer(handle, "My message")
finest()
Short description

Logs a message with level "FINEST"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.Logger.finest(handle, "My message")
info()
Short description

Logs a message with level "INFO"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.Logger.info(handle, "My message")
isLoggable()
Short description

Check whether a message with a certain log level will be forwarded with the current level setting or not.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

level

ENUM Level

Log level

Return values
Name Type Description

loggable

BOOL

True if loggable, false if not

Sample
loggable = Log.Logger.isLoggable(handle, "INFO")
setLevel()
Short description

Sets the logging level of the logger.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

level

ENUM Level

Log level

Sample
Log.Logger.setLevel(handle, "WARNING")
severe()
Short description

Logs a message with level "SEVERE"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.Logger.severe(handle, "My message")
warning()
Short description

Logs a message with level "WARNING"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.Logger.warning(handle, "My message")

Log.SharedLogger

Short description

Shared logger which can be accessed from any app. The handle created does not 'own' the logger. Messages can be logged to the logger by using the functions named after the log levels (info, warning, severe, …​). To get output from the logger, a handler must be attached to it and connected to a sink. See Log.Handler for more information. logger = Log.SharedLogger.create("mySharedLogger") logger:warning("This is a warning")

Functions

create()
Short description

Creates a new Log.SharedLogger instance.

Parameters
Name Type Description

loggerName

STRING

Name of the logger

Return values
Name Type Description

handle

HANDLE

The new instance

Sample
local handle = Log.SharedLogger.create("loggerName")
fine()
Short description

Logs a message with level "FINE"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.SharedLogger.fine(handle, "My message")
finer()
Short description

Logs a message with level "FINER"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.SharedLogger.finer(handle, "My message")
finest()
Short description

Logs a message with level "FINEST"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.SharedLogger.finest(handle, "My message")
info()
Short description

Logs a message with level "INFO"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.SharedLogger.info(handle, "My message")
isLoggable()
Short description

Check whether a message with a certain log level will be forwarded with the current level setting or not.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

level

ENUM Level

Log level

Return values
Name Type Description

loggable

BOOL

True if loggable, false if not

Sample
loggable = Log.SharedLogger.isLoggable(handle, "INFO")
setLevel()
Short description

Sets the logging level of the logger.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

level

ENUM Level

Log level

Sample
Log.SharedLogger.setLevel(handle, "WARNING")
severe()
Short description

Logs a message with level "SEVERE"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.SharedLogger.severe(handle, "My message")
warning()
Short description

Logs a message with level "WARNING"

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

msg

STRING

The message to print out

Sample
Log.SharedLogger.warning(handle, "My message")

MachineLearning

Short description

Machine learning tools for data understanding and prediction. The Machine Learning API trains classifiers and makes predictions on samples formed by collecting measurements of data as rows in a matrix. Helpers to partition data into training and evaluation set and other convenience functions to manipulate the raw dataset are also included. Classifiers in general support both regression and classification tasks. The selection is made when creating the dataset. Algorithms included - DataSet container for labeled samples. - Classifiers: Neural net, Random Forest, k-Nearest Neighbor, Support Vector Machines, Bayes, Fisher Linear Discriminant - Data dimensionality reduction: Principal Component Analysis (PCA), k-Means clustering - Methods for evaluating classifier accuracy - Methods for data statistics, selection and preconditioning.

Overview

MachineLearning.Bayes

Short description

Bayes, or as it is sometimes known, Normal Bayes Classifier, is a really simple classifier. It has no parameters and tries to separate classes by assuming normal distribution within each feature. For data that is approximately Gaussian this classifier works well and is quite quick to evaluate.

Functions

clear()
Short description

Clear internal data of the classifier.

Parameters
Name Type Description

bayes

HANDLE

The classifier instance to use.

Sample
MachineLearning.Bayes.clear(bayes)
create()
Short description

Creates a new Bayes classifier.

Return values
Name Type Description

bayes

HANDLE

The new Bayes handle

Sample
bayes = MachineLearning.Bayes.create()
getAccuracy()
Short description

Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.

Parameters
Name Type Description

bayes

HANDLE

The classifier instance to use.

dataSet

OBJECT MachineLearning.DataSet

The dataset to use

Return values
Name Type Description

accuracy

FLOAT

The accuracy rate. Computed as correct classifications divided by total amount of samples.

confusionMatrix

OBJECT Matrix

Confusion matrix for dataset and classifier.

confusionMatrixLabels

INT

The label key for the confusion matrix.

Sample
accuracy, confusionMatrix = MachineLearning.Bayes.getAccuracy(bayes, dataSet)
getFeatureCount()
Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name Type Description

bayes

HANDLE

The classifier instance to use.

Return values
Name Type Description

featureCount

INT

The amount of features per sample.

Sample
trained = MachineLearning.Bayes.getFeatureCount(bayes)
isTrained()
Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name Type Description

bayes

HANDLE

The classifier instance to use.

Return values
Name Type Description

trained

BOOL

True if the classifier is trained.

Sample
trained = MachineLearning.Bayes.isTrained(bayes)
load()
Short description

Load a Bayes classifier from disk.

Parameters
Name Type Description

path

STRING

The path to the classifier

Return values
Name Type Description

bayes

HANDLE

The Bayes handle to the loaded object.

Sample
bayes = MachineLearning.Bayes.load(path)
predict()
Short description

Classify a sample using the trained classifier.

Parameters
Name Type Description

bayes

HANDLE

The classifier instance to use.

sample

OBJECT Matrix

A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name Type Description

class

FLOAT

Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample
class = MachineLearning.Bayes.predict(bayes, sample)
save()
Short description

Save a Bayes classifier to disk.

Parameters
Name Type Description

bayes

HANDLE

The classifier instance to use

path

STRING

The path at which to store the classifier

Return values
Name Type Description

success

BOOL

True if the file was successfully stored, false if storing failed.

Sample
success = MachineLearning.Bayes.save(bayes, path)
toString()
Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name Type Description

bayes

OBJECT MachineLearning.Bayes

The input classifier data

Return values
Name Type Description

string

STRING

Description of the classifier

Sample
print("Description: " .. MachineLearning.Bayes.toString(bayes))
train()
Short description

Perform training on data supplied in a DataSet object.

Parameters
Name Type Description

bayes

HANDLE

The classifier instance to use

dataSet

OBJECT MachineLearning.DataSet

Input dataset

Return values
Name Type Description

success

BOOL

True if classifier was successfully trained.

Sample
success = MachineLearning.Bayes.train(bayes, dataSet)

MachineLearning.DataSet

Short description

Training data container for classical machine learning applications. Stores samples and corresponding labels for input to different classifiers. It is not intended for use together with DeepNeuralNetwork applications. Samples are always floating point values, but labels are integer values for classification tasks and floating point values for regression tasks. It’s possible to also supply weights per sample which some algorithms make use of during training.

Functions

append()
Short description

Append one or multiple samples to the internal list of samples.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

samples

OBJECT Matrix

Training sample(s). Each row is considered a separate sample. To add more samples at the same time use a matrix of multiple rows.

labels

AUTO

Training label(s). If all samples belong to the same class send a single label value. Otherwise there should be one sample per row in the samples matrix.

weight

OBJECT Matrix

Optional weights for each sample. This matrix must be single column and have as many rows as samples

Return values
Name Type Description

success

BOOL

True if data was successfully added.

Sample
MachineLearning.DataSet.append(dataSet, sample, label)
calculateNormalization()
Short description

Calculate a matrix with the mean and standard deviation for each feature. This matrix is convenient to use as input for normalizing dataset objects as well as raw matrices for example before classification. The matrix consist of the mean and standard deviation for each sample. Means are in the first row, standard deviations in the second.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

Return values
Name Type Description

normalization

OBJECT Matrix

The normalization matrix.

Sample
normalization = MachineLearning.DataSet.calculateNormalization(dataSet)
calculateProjection()
Short description

Calculate a matrix with the means of each feature in the first row and principal component eigen vectors in the following rows. The total height of the returned matrix minus one corresponds to the output dimension after projection.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

maxDimensions

INT

Set this value to determine the dimensions of the output. To keep all set to 0 or the original feature size.

retainVariance

FLOAT

Set this to select how much of the original signal to keep. If set to 0.5 it means that at least 50% of the signal energy remains after projection.

Return values
Name Type Description

projection

OBJECT Matrix

The projection matrix.

Sample
projection = MachineLearning.DataSet.calculateProjection(dataSet, maxDimensions, retainVariance)
calculateStatistics()
Short description

Calculate and return statistics for the dataset object.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

Return values
Name Type Description

mean

FLOAT

A vector containing the mean for each feature.

std

FLOAT

A vector containing the standard deviation for each feature.

min

FLOAT

A vector containing the minimum value for each feature.

max

FLOAT

A vector containing the maximum value for each feature.

Sample
mean, std, min, max = MachineLearning.DataSet.calculateStatistics(dataSet)
clear()
Short description

Remove all internally stored samples. Clearing out samples reduces memory usage and can be useful when large datasets are used for training.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

Sample
MachineLearning.DataSet.clear(dataSet)
create()
Short description

Creates a new DataSet object

Parameters
Name Type Description

labelType

ENUM LabelType

Create a dataset of the selected type.

Return values
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The new dataset.

Sample
dataSet = MachineLearning.DataSet.create("CLASSIFICATION")
getFeature()
Short description

Return a feature from the sample set.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

index

INT

The index into the dataset. If left out all all features are returned. This is the same getSample without index.

Return values
Name Type Description

sample

OBJECT Matrix

The matrix corresponding to the selected feature index or in case index is left out all features. Each feature is a separate column.

Sample
feature = MachineLearning.DataSet.getFeature(dataSet, index)
getFeatureCount()
Short description

Return the number of values stored per sample. This is the same as the number of columns in each sample that has been added.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

Return values
Name Type Description

featureCount

INT

The amount of features

Sample
featureCount = MachineLearning.DataSet.getFeatureCount(dataSet)
getLabel()
Short description

Return label for a sample in the loaded set.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

index

INT

The index into the dataset. If left out all labels are returned.

Return values
Name Type Description

label

AUTO

The label corresponding to the selected sample index or all labels if no index is supplied.

Sample
label = MachineLearning.DataSet.getLabel(dataSet, index)
getSample()
Short description

Return a sample from the sample set.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

index

INT

The index into the dataset. If left out all samples are returned. This is the same as getFeature without index.

Return values
Name Type Description

sample

OBJECT Matrix

The matrix corresponding to the selected sample index or in case index is left out all samples. Each sample is a separate row.

Sample
sample = MachineLearning.DataSet.getSample(dataSet, index)
getSampleCount()
Short description

Return the amount of samples currently stored in the dataset.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

Return values
Name Type Description

samplesCount

INT

The amount of samples

Sample
samplesCount = MachineLearning.DataSet.getSampleCount(dataSet)
getSubset()
Short description

Return a new dataset object of a selected subset of the original dataset.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

start

INT

The start index at which to start extracting samples.

count

INT

The amount of samples to extract. If left out all samples after start will be extracted.

Return values
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The new dataset consisting of only selected samples.

Sample
sample = MachineLearning.DataSet.getSubset(dataSet, start, count)
getSubsetInterval()
Short description

Return a new dataset object of a selected subset of the original dataset. This function allows extraction of an interval of label values in case the LabelType is REGRESSION.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

minValue

FLOAT

The smallest value of a label to keep in the output.

maxValue

FLOAT

The largest value of a label to keep in the output.

Return values
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The new dataset consisting of all samples with labels in the specified region.

Sample
sample = MachineLearning.DataSet.getSubsetInterval(dataSet, minValue, maxValue)
getSubsetLabels()
Short description

Return a new dataset object of a selected subset of the original dataset. This function allows the extraction of specific labels in case the LabelType is CLASSIFICATION.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

labels

INT

A vector of labels to keep in the output.

Return values
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The new dataset consisting of all samples with the selected labels.

Sample
sample = MachineLearning.DataSet.getSubsetLabels(dataSet, labels)
getType()
Short description

Returns the type of the data set, either CLASSIFICATION or REGRESSION.

Parameters
Name Type Description

dataSet

CONST_OBJECT MachineLearning.DataSet

The input dataset.

Return values
Name Type Description

type

ENUM LabelType

The type of the data set

Sample
type = MachineLearning.getType(dataSet)
getWeight()
Short description

Return weight for a sample in the loaded set.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

index

INT

The index into the dataset. If left out all weights are returned.

Return values
Name Type Description

weight

AUTO

The weight corresponding to the selected sample index or all weights if no index is supplied.

Sample
weight = MachineLearning.DataSet.getWeight(dataSet, index)
normalize()
Short description

Apply a normalization matrix to a dataset object or another matrix. In both cases the dimensions must be compatible. Eg. the feature size of the dataset object or the amount of columns of the matrix must be equal to the columns of the normalization matrix.

Parameters
Name Type Description

source

OBJECT [API:DataFormat:]

Either a dataset object or a matrix.

normalization

OBJECT Matrix

A normalization matrix. Can be created using calculateNormalization or by manual composition.

Return values
Name Type Description

normalized

OBJECT [API:DataFormat:]

A normalized version of the source input.

Sample
normalized = MachineLearning.DataSet.normalize(source, normalization)
project()
Short description

Apply a projection matrix to a dataset object or another matrix. In both cases the dimensions must be compatible. Eg. the feature size of the dataset object or the amount of columns of the matrix must be equal to the columns of the projection matrix.

Parameters
Name Type Description

source

OBJECT [API:DataFormat:]

Either a dataset object or a matrix.

projection

OBJECT Matrix

A projection matrix. Can be created using calculateProjection or by manual composition.

Return values
Name Type Description

projected

OBJECT [API:DataFormat:]

The projected version of the source input.

Sample
projected = MachineLearning.DataSet.project(source, projection)
split()
Short description

Split a dataset object into two parts. The amount of samples in the larger set will be the same as the amount of samples in the smaller set times the input "factor". This means if factor is set to 3 that the first dataset object will be 3 times larger than the second. The sample selection is automatically randomized. To turn of randomization set the optional parameter "randomize" to false.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

factor

INT

The amount of samples in the major set compared to the minor set.

randomize

BOOL

Select if samples should be randomized before split. Default is true.

Return values
Name Type Description

major

OBJECT MachineLearning.DataSet

A new dataset containing the larger part of the samples.

minor

OBJECT MachineLearning.DataSet

A new dataset containing the smaller part of the samples.

Sample
major, minor = MachineLearning.DataSet.split(dataSet, 3)
toString()
Short description

Get a brief string description of the dataset. This is equal to the text shown in the debugger to describe the dataset.

Parameters
Name Type Description

dataSet

OBJECT MachineLearning.DataSet

The input dataset

Return values
Name Type Description

string

STRING

Description of the dataset

Sample
print("Description: " .. MachineLearning.DataSet.toString(dataSet))

MachineLearning.Fisher

Short description

Fisher’s linear discriminant, sometimes called Linear Discriminant Analysis (LDA) is a method to find a vector which linearly separates two classes in an optimal way. This vector is found so that samples from different classes projected onto this vector end up as far apart a possible. For this reason Fisher can be used to understand what features of a data set have the most discriminating effect by looking at this vector. This is useful when trying to reduce the feature size input to another classifier without loosing too much performance.

Functions

clear()
Short description

Clear internal data of the classifier.

Parameters
Name Type Description

fisher

HANDLE

The classifier instance to use.

Sample
MachineLearning.Fisher.clear(fisher)
create()
Short description

Creates a handle for Fisher’s linear discriminant.

Return values
Name Type Description

fisher

HANDLE

The new Fisher handle

Sample
lda = MachineLearning.Fisher.create()
getAccuracy()
Short description

Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.

Parameters
Name Type Description

fisher

HANDLE

The classifier instance to use.

dataSet

OBJECT MachineLearning.DataSet

The dataset to use

Return values
Name Type Description

accuracy

FLOAT

The accuracy rate. Computed as correct classifications divided by total amount of samples.

confusionMatrix

OBJECT Matrix

Confusion matrix for dataset and classifier.

confusionMatrixLabels

INT

The label key for the confusion matrix.

Sample
accuracy, confusionMatrix = MachineLearning.Fisher.getAccuracy(fisher, dataSet)
getFeatureCount()
Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name Type Description

fisher

HANDLE

The classifier instance to use.

Return values
Name Type Description

featureCount

INT

The amount of features per sample.

Sample
trained = MachineLearning.Fisher.getFeatureCount(fisher)
getProjectionVector()
Short description

Returns the estimated projection direction for this classifier. This can be used to better understand what features are distinguishing when separating the objects.

Parameters
Name Type Description

fisher

HANDLE

The classifier instance to use.

Return values
Name Type Description

vector

FLOAT

A vector with the coefficients for projection.

Sample
vector = MachineLearning.Fisher.getProjectionVector(fisher)
isTrained()
Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name Type Description

fisher

HANDLE

The classifier instance to use.

Return values
Name Type Description

trained

BOOL

True if the classifier is trained.

Sample
trained = MachineLearning.Fisher.isTrained(fisher)
load()
Short description

Load a Fisher classifier from disk.

Parameters
Name Type Description

path

STRING

The path to the classifier

Return values
Name Type Description

fisher

HANDLE

The Fisher handle to the loaded object.

Sample
fisher = MachineLearning.Fisher.load(path)
predict()
Short description

Classify a sample using the trained classifier.

Parameters
Name Type Description

fisher

HANDLE

The classifier instance to use.

sample

OBJECT Matrix

A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name Type Description

class

FLOAT

Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample
class = MachineLearning.Fisher.predict(fisher, sample)
save()
Short description

Save a Fisher classifier to disk.

Parameters
Name Type Description

fisher

HANDLE

The classifier instance to use

path

STRING

The path at which to store the classifier

Return values
Name Type Description

success

BOOL

True if the file was successfully stored, false if storing failed.

Sample
success = MachineLearning.Fisher.save(fisher, path)
toString()
Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name Type Description

fisher

OBJECT MachineLearning.Fisher

The input classifier data

Return values
Name Type Description

string

STRING

Description of the classifier

Sample
print("Description: " .. MachineLearning.Fisher.toString(fisher))
train()
Short description

Perform training on data supplied in a DataSet object.

Parameters
Name Type Description

fisher

HANDLE

The classifier instance to use

dataSet

OBJECT MachineLearning.DataSet

Input dataset

Return values
Name Type Description

success

BOOL

True if classifier was successfully trained.

Sample
success = MachineLearning.Fisher.train(fisher, dataSet)

MachineLearning.KMeansClustering

Short description

k-Means Clustering is a technique mainly used to find structure in unordered data. It’s an iterative method which tries to group samples into clusters in a two step process. First a start solution is created by randomizing a number of cluster centers. Then features are assigned to clusters based on the feature distance to the cluster centers and secondly the center of each cluster is updated based on its feature members. This is iterated for a selectable number of cycles. Note that KMeansClustering in reality is a clustering algorithm and not really a classifier. It can be used for classification by checking what cluster a sample is closest to after training. Because of the clustering nature the default behavior is that the labels of the input data is updated with the result of the clustering operation. To disable this behavior set "updateInput" to false in setParameters.

Functions

clear()
Short description

Clear internal data of the classifier.

Parameters
Name Type Description

km

HANDLE

The classifier instance to use.

Sample
MachineLearning.KMeansClustering.clear(km)
create()
Short description

Creates a new KMeansClustering object.

Return values
Name Type Description

km

HANDLE

The new KMeansClustering handle

Sample
km = MachineLearning.KMeansClustering.create()
getClusterCenters()
Short description

Get the resulting cluster centers for evaluation of the result.

Parameters
Name Type Description

km

HANDLE

The classifier instance to use.

Return values
Name Type Description

clusters

OBJECT Matrix

The cluster centers with one position per row.

Sample
clusters = MachineLearning.KMeansClustering.getClusterCenters(km)
getCompactness()
Short description

Get the compactness of the clustering. This is a measure on how well classes could be separated and is calculated as the average distance from all samples to their cluster centers.

Parameters
Name Type Description

km

HANDLE

The classifier instance to use.

Return values
Name Type Description

compactness

FLOAT

The compactness of the clustering.

Sample
compactness = MachineLearning.KMeansClustering.getCompactness(km)
getFeatureCount()
Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name Type Description

km

HANDLE

The classifier instance to use.

Return values
Name Type Description

featureCount

INT

The amount of features per sample.

Sample
trained = MachineLearning.KMeansClustering.getFeatureCount(km)
isTrained()
Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name Type Description

km

HANDLE

The classifier instance to use.

Return values
Name Type Description

trained

BOOL

True if the classifier is trained.

Sample
trained = MachineLearning.KMeansClustering.isTrained(km)
load()
Short description

Load a KMeansClustering classifier from disk.

Parameters
Name Type Description

path

STRING

The path to the classifier

Return values
Name Type Description

km

HANDLE

The KMeansClustering handle to the loaded object.

Sample
km = MachineLearning.KMeansClustering.load(path)
predict()
Short description

Classify a sample using the trained classifier.

Parameters
Name Type Description

km

HANDLE

The classifier instance to use.

sample

OBJECT Matrix

A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name Type Description

class

FLOAT

Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample
class = MachineLearning.KMeansClustering.predict(km, sample)
save()
Short description

Save a KMeansClustering classifier to disk.

Parameters
Name Type Description

km

HANDLE

The classifier instance to use

path

STRING

The path at which to store the classifier

Return values
Name Type Description

success

BOOL

True if the file was successfully stored, false if storing failed.

Sample
success = MachineLearning.KMeansClustering.save(km, path)
setParameters()
Short description

Set parameters for how training should be done.

Parameters
Name Type Description

km

HANDLE

The classifier instance to use

numberOfClusters

INT

The number of clusters to fit to data (number of classes).

initMethod

ENUM InitMethod

Select the way to initialize the algorithm.

iterations

INT

Select the number of iterations to run the algorithm. Default is 100.

updateInput

BOOL

Select if the labels of the dataset should be updated. Default is true.

Return values
Name Type Description

success

BOOL

True if successful, false if combination of parameters is unsupported.

Sample
success = MachineLearning.KMeansClustering.setParameters(km, "RANDOM")
toString()
Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name Type Description

km

OBJECT MachineLearning.KMeansClustering

The input classifier data

Return values
Name Type Description

string

STRING

Description of the classifier

Sample
print("Description: " .. MachineLearning.KMeansClustering.toString(km))
train()
Short description

Perform training on data supplied in a DataSet object.

Parameters
Name Type Description

km

HANDLE

The classifier instance to use

dataSet

OBJECT MachineLearning.DataSet

Input dataset

Return values
Name Type Description

success

BOOL

True if classifier was successfully trained.

Sample
success = MachineLearning.KMeansClustering.train(km, dataSet)

MachineLearning.KNearestNeighbors

Short description

k Nearest Neighbors or kNN for short, is basically a voting scheme based on proximity. During training the training samples are collected and are themselves stored for later use during classification. During classification the features of a new sample are compared to features of the k closest samples from the training dataset. The classification is given by the majority vote of these k samples.

Functions

clear()
Short description

Clear internal data of the classifier.

Parameters
Name Type Description

knn

HANDLE

The classifier instance to use.

Sample
MachineLearning.KNearestNeighbors.clear(knn)
create()
Short description

Creates a new KNearestNeighbors handle

Return values
Name Type Description

knn

HANDLE

The new KNearestNeighbors handle

Sample
knn = MachineLearning.KNearestNeighbors.create()
getAccuracy()
Short description

Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.

Parameters
Name Type Description

knn

HANDLE

The classifier instance to use.

dataSet

OBJECT MachineLearning.DataSet

The dataset to use

Return values
Name Type Description

accuracy

FLOAT

The accuracy rate. Computed as correct classifications divided by total amount of samples.

confusionMatrix

OBJECT Matrix

Confusion matrix for dataset and classifier.

confusionMatrixLabels

INT

The label key for the confusion matrix.

Sample
accuracy, confusionMatrix = MachineLearning.KNearestNeighbors.getAccuracy(knn, dataSet)
getFeatureCount()
Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name Type Description

knn

HANDLE

The classifier instance to use.

Return values
Name Type Description

featureCount

INT

The amount of features per sample.

Sample
trained = MachineLearning.KNearestNeighbors.getFeatureCount(knn)
isTrained()
Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name Type Description

knn

HANDLE

The classifier instance to use.

Return values
Name Type Description

trained

BOOL

True if the classifier is trained.

Sample
trained = MachineLearning.KNearestNeighbors.isTrained(knn)
load()
Short description

Load a KNearestNeighbors classifier from disk.

Parameters
Name Type Description

path

STRING

The path to the classifier

Return values
Name Type Description

knn

HANDLE

The KNearestNeighbors handle to the loaded object.

Sample
knn = MachineLearning.KNearestNeighbors.load(path)
predict()
Short description

Classify a sample using the trained classifier.

Parameters
Name Type Description

knn

HANDLE

The classifier instance to use.

sample

OBJECT Matrix

A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name Type Description

class

FLOAT

Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample
class = MachineLearning.KNearestNeighbors.predict(knn, sample)
save()
Short description

Save a KNearestNeighbors classifier to disk.

Parameters
Name Type Description

knn

HANDLE

The classifier instance to use

path

STRING

The path at which to store the classifier

Return values
Name Type Description

success

BOOL

True if the file was successfully stored, false if storing failed.

Sample
success = MachineLearning.KNearestNeighbors.save(knn, path)
setParameters()
Short description

Set parameters for how training should be done.

Parameters
Name Type Description

handle

HANDLE

The classifier instance to use

numberOfNeighbors

INT

Number of neighbors to use when calculating.

Return values
Name Type Description

success

BOOL

True if successful, false if combination of parameters is unsupported.

Sample
success = MachineLearning.KNearestNeighbors.setParameters(knn, 13)
toString()
Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name Type Description

knn

OBJECT MachineLearning.KNearestNeighbors

The input classifier data

Return values
Name Type Description

string

STRING

Description of the classifier

Sample
print("Description: " .. MachineLearning.KNearestNeighbors.toString(knn))
train()
Parameters
Name Type Description

knn

HANDLE

The classifier instance to use

dataSet

OBJECT MachineLearning.DataSet

Input dataset

Return values
Name Type Description

success

BOOL

True if classifier was successfully trained.

Sample
MachineLearning.KNearestNeighbors.train(knn, dataSet)

MachineLearning.NeuralNet

Short description

A neural network also known as Artificial Neural Net (ANN) or multi-layer perceptron (MLP) is a model initially created to mimic the function of neurons. Note that this is a shallow fully connected neural network model that can be trained on device. For larger Deep Neural Networks and Convolutional Networks see the DeepNeuralNetwork API. In a neural network there is an input layer, an output layer and a number of hidden layers. The input layer typically corresponds to the input features and the output layer to the output labels. In-between these two layers is an undecided number of hidden layers. The number of layers can be selected by the length of the "hiddenLayers" vector in the setParameters function and the amount of neurons in each layer by the value at each position in this vector. The first value corresponds to the layer closest to the input. Each neuron can be thought of as a simple decision point in the graph. How the decision is made is determined through training by means of back propagation on training data and by the selection of the activation function prior to training. One special feature of the neural network is that it can be trained incrementally. That is, it’s possible to train on different DataSet objects in sequence and get a final model with the accumulated result. The limitation of this is that only new samples of the same format can be added, no new features can be introduced between increments. Be sure to use the "clear" function if incremental training is not intended!

Functions

clear()
Short description

Clear internal data of the classifier. Use this to forget previous samples and reset all network weights.

Parameters
Name Type Description

nn

HANDLE

The classifier instance to use.

Sample
MachineLearning.NeuralNet.clear(nn)
create()
Short description

Creates a new NeuralNet

Return values
Name Type Description

nn

HANDLE

The new NeuralNet handle

Sample
nn = MachineLearning.NeuralNet.create()
getAccuracy()
Short description

Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.

Parameters
Name Type Description

nn

HANDLE

The classifier instance to use.

dataSet

OBJECT MachineLearning.DataSet

The dataset to use

Return values
Name Type Description

accuracy

FLOAT

The accuracy rate. Computed as correct classifications divided by total amount of samples.

confusionMatrix

OBJECT Matrix

Confusion matrix for dataset and classifier.

confusionMatrixLabels

INT

The label key for the confusion matrix.

Sample
accuracy, confusionMatrix = MachineLearning.NeuralNet.getAccuracy(nn, dataSet)
getFeatureCount()
Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name Type Description

nn

HANDLE

The classifier instance to use.

Return values
Name Type Description

featureCount

INT

The amount of features per sample.

Sample
trained = MachineLearning.NeuralNet.getFeatureCount(nn)
isTrained()
Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name Type Description

nn

HANDLE

The classifier instance to use.

Return values
Name Type Description

trained

BOOL

True if the classifier is trained.

Sample
trained = MachineLearning.NeuralNet.isTrained(nn)
load()
Short description

Load a NeuralNet classifier from disk.

Parameters
Name Type Description

path

STRING

The path to the classifier

Return values
Name Type Description

nn

HANDLE

The NeuralNet handle to the loaded object.

Sample
nn = MachineLearning.NeuralNet.load(path)
predict()
Short description

Classify a sample using the trained classifier.

Parameters
Name Type Description

nn

HANDLE

The classifier instance to use.

sample

OBJECT Matrix

A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name Type Description

class

FLOAT

Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample
class = MachineLearning.NeuralNet.predict(nn, sample)
save()
Short description

Save a NeuralNet classifier to disk.

Parameters
Name Type Description

nn

HANDLE

The classifier instance to use

path

STRING

The path at which to store the classifier

Return values
Name Type Description

success

BOOL

True if the file was successfully stored, false if storing failed.

Sample
success = MachineLearning.NeuralNet.save(nn, path)
setParameters()
Short description

Set parameters for how training should be done.

Parameters
Name Type Description

handle

HANDLE

The classifier instance to use

hiddenLayers

INT

A vector specifying how many hidden neurons there should be in each layer. The first entry is closest to the input layer.

activationFunction

ENUM ActivationFunction

Type of activation function to use in the perceptrons. If omitted SIGMOID is used.

weightScale

FLOAT

Sets the weight scale for back propagation calculations.

momentumScale

FLOAT

Sets the momentum scale for back propagation calculations.

Return values
Name Type Description

success

BOOL

True if successful, false if combination of parameters is unsupported.

Sample
success = MachineLearning.NeuralNet.setParameters(nn, {3, 4}, "SIGMOID")
toString()
Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name Type Description

nn

OBJECT MachineLearning.NeuralNet

The input classifier data

Return values
Name Type Description

string

STRING

Description of the classifier

Sample
print("Description: " .. MachineLearning.NeuralNet.toString(nn))
train()
Short description

Perform training on data supplied in a DataSet object. Note that training is done incrementally. To start out from the beginning use "clear" or create a new NeuralNet handle.

Parameters
Name Type Description

nn

HANDLE

The classifier instance to use

dataSet

OBJECT MachineLearning.DataSet

Input dataset

Return values
Name Type Description

success

BOOL

True if classifier was successfully trained.

Sample
success = MachineLearning.NeuralNet.train(nn, dataSet)

MachineLearning.RandomForest

Short description

The random forest method is a method based on decision trees. During training multiple decision trees are created based on subsets of the training dataset. During classification each tree is evaluated on the data and the majority vote wins.

Functions

clear()
Short description

Clear internal data of the classifier.

Parameters
Name Type Description

rf

HANDLE

The classifier instance to use.

Sample
MachineLearning.RandomForest.clear(rf)
create()
Short description

Creates a new RandomForest

Return values
Name Type Description

rf

HANDLE

The new RandomForest handle

Sample
rf = MachineLearning.RandomForest.create()
getAccuracy()
Short description

Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.

Parameters
Name Type Description

rf

HANDLE

The classifier instance to use.

dataSet

OBJECT MachineLearning.DataSet

The data set to use

Return values
Name Type Description

accuracy

FLOAT

The accuracy rate. Computed as correct classifications divided by total amount of samples.

confusionMatrix

OBJECT Matrix

Confusion matrix for data set and classifier.

confusionMatrixLabels

INT

The label key for the confusion matrix.

Sample
accuracy, confusionMatrix = MachineLearning.RandomForest.getAccuracy(rf, dataSet)
getFeatureCount()
Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name Type Description

rf

HANDLE

The classifier instance to use.

Return values
Name Type Description

featureCount

INT

The amount of features per sample.

Sample
trained = MachineLearning.RandomForest.getFeatureCount(rf)
isTrained()
Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name Type Description

rf

HANDLE

The classifier instance to use.

Return values
Name Type Description

trained

BOOL

True if the classifier is trained.

Sample
trained = MachineLearning.RandomForest.isTrained(rf)
load()
Short description

Load a RandomForest classifier from disk.

Parameters
Name Type Description

path

STRING

The path to the classifier

Return values
Name Type Description

rf

HANDLE

The RandomForest handle to the loaded object.

Sample
rf = MachineLearning.RandomForest.load(path)
predict()
Short description

Classify a sample using the trained classifier.

Parameters
Name Type Description

rf

HANDLE

The classifier instance to use.

sample

OBJECT Matrix

A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name Type Description

class

FLOAT

Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample
class = MachineLearning.RandomForest.predict(rf, sample)
save()
Short description

Save a RandomForest classifier to disk.

Parameters
Name Type Description

rf

HANDLE

The classifier instance to use

path

STRING

The path at which to store the classifier

Return values
Name Type Description

success

BOOL

True if the file was successfully stored, false if storing failed.

Sample
success = MachineLearning.RandomForest.save(rf, path)
setParameters()
Short description

Set parameters for how training should be done.

Parameters
Name Type Description

handle

HANDLE

The classifier instance to use

minSamplesPerNode

INT

If the number of samples in a node is less than this value the node will not be split. Default is 10.

regressionAccuracy

FLOAT

Limit to determine when to stop splitting nodes for regression trees. Default is 0.01.

activeVarCount

INT

The size of the subset of features at each tree node that are used to find the best split(s). If set to 0 it is automatically set to the square root of the number of samples.

maxCategories

INT

In cases with more than 2 classes this limitation is used to reduce computation time at the cost of precision. Use a higher value for more precise results. Default is 10.

maxTreeDepth

INT

If no other termination criteria stops the splitting this determines the maximum allowed depth of a tree. Default is 10.

Return values
Name Type Description

success

BOOL

True if successful, false if combination of parameters is unsupported.

Sample
success = MachineLearning.RandomForest.setParameters(rf, ...)
toString()
Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name Type Description

rf

OBJECT MachineLearning.RandomForest

The input classifier data

Return values
Name Type Description

string

STRING

Description of the classifier

Sample
print("Description: " .. MachineLearning.RandomForest.toString(rf))
train()
Short description

Perform training on data supplied in a DataSet object.

Parameters
Name Type Description

rf

HANDLE

The classifier instance to use

dataSet

OBJECT MachineLearning.DataSet

Input dataset

Return values
Name Type Description

success

BOOL

True if classifier was successfully trained.

Sample
success = MachineLearning.RandomForest.train(rf, dataSet)

MachineLearning.SupportVectorMachine

Short description

Support Vector Machines are used to distinguish multidimensional data by creating a decision boundary that maximizes the orthogonal distance between classes. A Support Vector Machine can be configured to support non-linear cases by using a non-linear kernel. A special case of the Support Vector Machine is the single class case where a classifier can be trained on samples only from one class to learn to recognize if new samples belong to this class or not. This requires training data set with only one input class.

Functions

clear()
Short description

Clear internal data of the classifier.

Parameters
Name Type Description

svm

HANDLE

The classifier instance to use.

Sample
MachineLearning.SupportVectorMachine.clear(svm)
create()
Short description

Creates a new SupportVectorMachine

Return values
Name Type Description

svm

HANDLE

The new SupportVectorMachine

Sample
svm = MachineLearning.SupportVectorMachine.create()
getAccuracy()
Short description

Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.

Parameters
Name Type Description

svm

HANDLE

The classifier instance to use.

dataSet

OBJECT MachineLearning.DataSet

The data set to use

Return values
Name Type Description

accuracy

FLOAT

The accuracy rate. Computed as correct classifications divided by total amount of samples.

confusionMatrix

OBJECT Matrix

Confusion matrix for data set and classifier.

confusionMatrixLabels

INT

The label key for the confusion matrix.

Sample
accuracy, confusionMatrix = MachineLearning.SupportVectorMachine.getAccuracy(svm, dataSet)
getFeatureCount()
Short description

Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.

Parameters
Name Type Description

svm

HANDLE

The classifier instance to use.

Return values
Name Type Description

featureCount

INT

The amount of features per sample.

Sample
trained = MachineLearning.SupportVectorMachine.getFeatureCount(svm)
isTrained()
Short description

Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.

Parameters
Name Type Description

svm

HANDLE

The classifier instance to use.

Return values
Name Type Description

trained

BOOL

True if the classifier is trained.

Sample
trained = MachineLearning.SupportVectorMachine.isTrained(svm)
load()
Short description

Load a SupportVectorMachine classifier from disk.

Parameters
Name Type Description

path

STRING

The path to the classifier

Return values
Name Type Description

svm

HANDLE

The SupportVectorMachine handle to the loaded object.

Sample
svm = MachineLearning.SupportVectorMachine.load(path)
predict()
Short description

Classify a sample using the trained classifier.

Parameters
Name Type Description

svm

HANDLE

The classifier instance to use.

sample

OBJECT Matrix

A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample.

Return values
Name Type Description

class

FLOAT

Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels.

Sample
class = MachineLearning.SupportVectorMachine.predict(svm, sample)
save()
Short description

Save a SupportVectorMachine classifier to disk.

Parameters
Name Type Description

svm

HANDLE

The classifier instance to use

path

STRING

The path at which to store the classifier

Return values
Name Type Description

success

BOOL

True if the file was successfully stored, false if storing failed.

Sample
success = MachineLearning.SupportVectorMachine.save(svm, path)
setParameters()
Short description

Set parameters for how training should be done.

Parameters
Name Type Description

handle

HANDLE

The classifier instance to use

nu

FLOAT

Parameter commonly known as nu for Support Vector Machine optimization problems. It tweaks the flexibility/smoothing of the decision boundaries and the complexity of the final classifier. Should be a value in the range of 0 to 1.

kernelType

ENUM KernelType

Type of kernel used in SupportVectorMachine computation.

sigma

FLOAT

Standard deviation sigma for the GAUSSIAN kernel function. For the LINEAR KernelType this value is unused.

singleClass

BOOL

Select this if only samples of one class is supplied. Learns to detect anomalies from this class. Not used in the regression case.

c

FLOAT

SVM C parameter for regression problems. Not used in the classification case.

Return values
Name Type Description

success

BOOL

Returns true if successful.

Sample
success = MachineLearning.SupportVectorMachine.setParameters(svm, nu, kernelType, gamma)
toString()
Short description

Get a brief string description of the classifier. This is equal to the text shown in the debugger.

Parameters
Name Type Description

svm

OBJECT MachineLearning.SupportVectorMachine

The input classifier data

Return values
Name Type Description

string

STRING

Description of the classifier

Sample
print("Description: " .. MachineLearning.SupportVectorMachine.toString(svm))
train()
Short description

Perform training on data supplied in a DataSet object.

Parameters
Name Type Description

svm

HANDLE

The classifier instance to use

dataSet

OBJECT MachineLearning.DataSet

Input data set

Return values
Name Type Description

success

BOOL

True if classifier was successfully trained. Nil if dataSet is nil.

Sample
MachineLearning.SupportVectorMachine.train(svm, dataSet)

Matrix

Short description

A 2D matrix of floating-point values.

Functions

add()
Short description

Adds two matrices of the same size.

Parameters
Name Type Description

m1

CONST_OBJECT Matrix

The first matrix to add

m2

CONST_OBJECT Matrix

The second matrix to add

Return values
Name Type Description

matrix

OBJECT Matrix

The sum

Sample
local matrix = Matrix.add(m1, m2)
addConstant()
Short description

Adds the value to each matrix element.

Parameters
Name Type Description

matrix

OBJECT Matrix

The matrix to add to

value

FLOAT

The value to add to each element in the matrix.

Sample
Matrix.addConstant(matrix, value)
clone()
Short description

Duplicates the matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The instance to use

Return values
Name Type Description

clonedMatrix

OBJECT Matrix

The duplicated matrix

Sample
local clonedMatrix = Matrix.clone(matrix)
concatenate()
Short description

Returns the concatenation of the two matrices.

Parameters
Name Type Description

m1

CONST_OBJECT Matrix

The first matrix to concatenate

m2

CONST_OBJECT Matrix

The second matrix to concatenate

concatHorizontally

BOOL

If the concatenation shall be horizontally or vertically

Return values
Name Type Description

concatMatrix

OBJECT Matrix

The new matrix

Sample
local concatMatrix = Matrix.concatenate(m1, m2, concatHorizontally)
create()
Short description

Creates a new matrix.

Parameters
Name Type Description

rows

INT

The number of rows

cols

INT

The number of columns

Return values
Name Type Description

matrix

OBJECT Matrix

The new matrix

Sample
local matrix = Matrix.create(rows, cols)
createFromVector()
Short description

Creates a new matrix from a vector in row-major order.

Parameters
Name Type Description

vector

FLOAT

The vector of elements to create the matrix from

rows

INT

The number of rows

cols

INT

The number of columns

Return values
Name Type Description

matrix

OBJECT Matrix

The new matrix

Sample
local matrix = Matrix.createFromVector(vector, rows, cols)
createIdentity()
Short description

Creates a new identity matrix.

Parameters
Name Type Description

size

INT

The number of rows and columns

Return values
Name Type Description

matrix

OBJECT Matrix

The new identity matrix

Sample
local matrix = Matrix.createIdentity(size)
determinant()
Short description

Returns the determinant of the matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix for which to calculate the determinant

Return values
Name Type Description

det

FLOAT

The determinant of the matrix

Sample
local det = Matrix.determinant(matrix)
getColumn()
Short description

Returns one or multiple columns of the matrix. The columns are returned as a MxK matrix, where M is the number of rows of the original matrix and K is the number of column indices in colIndex.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix from which to get the columns

colIndex

INT

The index of the matrix columns

Return values
Name Type Description

columns

OBJECT Matrix

The wanted matrix columns

Sample
local columns = Matrix.getColumn(matrix, colIndex)
getRow()
Short description

Returns one or multiple rows of the matrix. The rows are returned as a KxN matrix, where N is the number of columns of the original matrix and K is the number of row indices in rowIndex.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix from which to get the rows

rowIndex

INT

The index of the matrix rows

Return values
Name Type Description

rows

OBJECT Matrix

The wanted matrix rows

Sample
local rows = Matrix.getRow(matrix, rowIndex)
getSize()
Short description

Returns the number of rows and columns of the matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The instance to use

Return values
Name Type Description

rows

INT

The number of rows in the matrix

cols

INT

The number of columns in the matrix

Sample
local rows, columns= Matrix.getSize(matrix)
getValue()
Short description

Returns the value of the indexed matrix element. The first element has index (0,0).

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix in which to get a value

rowIndex

INT

The row index of the matrix element

colIndex

INT

The column index of the matrix element

Return values
Name Type Description

value

FLOAT

The value

Sample
local value = Matrix.getValue(matrix, rowIndex, colIndex)
invert()
Short description

Returns the inverse matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The instance to use

Return values
Name Type Description

inversedMatrix

OBJECT Matrix

The inverse matrix.

Sample
local inversedMatrix = Matrix.invert(matrix)
max()
Short description

Returns the maximum value of the matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix in which to find the maximum value

Return values
Name Type Description

max

FLOAT

The maximum value of the matrix

Sample
local max = Matrix.max(matrix)
min()
Short description

Returns the minimum value of the matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix in which to find the minimum value

Return values
Name Type Description

min

FLOAT

The minimum value of the matrix

Sample
local min = Matrix.min(matrix)
multiply()
Short description

Multiplies two matrices. The first matrix must have the same number of columns as the second matrix has rows.

Parameters
Name Type Description

m1

CONST_OBJECT Matrix

The first matrix to multiply

m2

CONST_OBJECT Matrix

The second matrix to multiply

Return values
Name Type Description

matrix

OBJECT Matrix

The matrix product

Sample
local matrix = Matrix.multiply(m1, m2)
multiplyConstant()
Short description

Multiplies each matrix element with the value.

Parameters
Name Type Description

matrix

OBJECT Matrix

The matrix to multiply by constant

value

FLOAT

The value with which to multiply all elements in the matrix.

Sample
Matrix.multiplyConstant(matrix, value)
norm()
Short description

Returns the Frobenius norm of the matrix, the square root of the sum of the squares of its elements.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix to calculate the norm for

Return values
Name Type Description

norm

FLOAT

The norm of the matrix

Sample
local norm = Matrix.norm(matrix)
setAll()
Short description

Sets the whole matrix to the same value.

Parameters
Name Type Description

matrix

OBJECT Matrix

The matrix to set

value

FLOAT

The value with which to set the whole matrix.

Sample
Matrix.setAll(matrix, value)
setColumn()
Short description

Sets one or multiple columns of the matrix.

Parameters
Name Type Description

matrix

OBJECT Matrix

The matrix in which to set the columns

colIndex

INT

The indices of the matrix columns to set

newColumn

CONST_OBJECT Matrix

The new matrix columns to set

Return values
Name Type Description

success

BOOL

True is input is valid

Sample
Matrix.setColumn(matrix, colIndex, newColumn)
setRow()
Short description

Sets one or multiple rows of the matrix.

Parameters
Name Type Description

matrix

OBJECT Matrix

The matrix in which to set the rows

rowIndex

INT

The index of the matrix rows to set

newRow

CONST_OBJECT Matrix

The new matrix rows

Return values
Name Type Description

success

BOOL

True is input is valid

Sample
Matrix.setRow(matrix, rowIndex, newRow)
setValue()
Short description

Sets the value in the indexed matrix element. The first element has index (0,0).

Parameters
Name Type Description

matrix

OBJECT Matrix

The matrix in which to set a value

rowIndex

INT

The row index of the matrix element to change

colIndex

INT

The column index of the matrix element to change

value

FLOAT

The value to set

Sample
Matrix.setValue(matrix, rowIndex, colIndex, value)
solve()
Short description

Computes the least squares solution to the equation system Ax = b. A is an NxM matrix. b is an Nx1 matrix. x is an Mx1 matrix and the solution to the equation system.

Parameters
Name Type Description

a

CONST_OBJECT Matrix

NxM matrix describing the left side of the equation system.

b

CONST_OBJECT Matrix

Nx1 matrix describing the right side of the equation system.

Return values
Name Type Description

x

OBJECT Matrix

Mx1 matrix containing the solution to the equation system.

residual

FLOAT

The average error by calculating (Ax - b).norm()/b.norm().

Sample
x, residual = Matrix.solve(a, b)
subtract()
Short description

Subtracts two matrices of the same size.

Parameters
Name Type Description

m1

CONST_OBJECT Matrix

The first matrix

m2

CONST_OBJECT Matrix

The matrix to subtract from the first

Return values
Name Type Description

matrix

OBJECT Matrix

The difference

Sample
local matrix = Matrix.subtract(m1, m2)
sumColumns()
Short description

Computes the sum of each column. The column sums are returned as a 1xN row matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix in which to calculate the column sums

Return values
Name Type Description

columnSums

OBJECT Matrix

The column sums of the matrix

Sample
local columnSums = Matrix.sumColumns(matrix)
sumRows()
Short description

Computes the sum of each row. The row sums are returned as a Mx1 column matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix in which to calculate the row sums

Return values
Name Type Description

rowSums

OBJECT Matrix

The row sums of the matrix

Sample
local rowSums = Matrix.sumRows(matrix)
svd()
Short description

Computes the singular value decomposition of an NxM matrix. U is the left singular vectors and U the right singular vectors corresponding to singular values S. In both U and V vectors are in the columns of each matrix such that matrix = U*diag(S)*V^T.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

Matrix to decompose.

Return values
Name Type Description

u

OBJECT Matrix

The left singular vectors with each vector in a column.

s

FLOAT

The singular values of the input matrix.

v

OBJECT Matrix

The right singular vectors with each vector in a column.

Sample
u, s, v = Matrix.svd(matrix)
tile()
Short description

Returns an n-by-m tiling of the matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix to tile

n

INT

The number of vertical repetitions

m

INT

The number of horizontal repetitions

Return values
Name Type Description

tileMatrix

OBJECT Matrix

The new matrix

Sample
local tileMatrix = Matrix.tile(matrix, n, m)
toImage()
Short description

Converts a matrix to a float64 image.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

Matrix to convert to image.

Return values
Name Type Description

image

OBJECT Image

Image created from the matrix.

Sample
image = Matrix.toImage(matrix)
toPoints()
Short description

Converts a matrix to a vector of 2D or 3D points.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

Matrix to convert to vector of points.

storedInColumns

BOOL

True if the points are in the columns of the matrix, false if in the rows of the matrix.

Return values
Name Type Description

points

OBJECT Point

Points created from the matrix.

Sample
points = Matrix.toPoints(matrix, storedInColumns)
toString()
Short description

Get a string representation of the matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

Input matrix

Return values
Name Type Description

str

STRING

String representation of the matrix

Sample
print("The matrix is: " .. Matrix.toString(matrix))
toVector()
Short description

Returns all elements of the matrix as vector in row-major order.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The matrix

Return values
Name Type Description

vector

FLOAT

Matrix elements as vector in row-major order

Sample
local vector = Matrix.toVector(matrix)
transpose()
Short description

Returns the transposed matrix.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

The instance to use

Return values
Name Type Description

transposedMatrix

OBJECT Matrix

The transposed matrix.

Sample
local transposedMatrix = Matrix.transpose(matrix)

Mesh

Short description

Object for a 3D surface represented by a triangle mesh. The mesh consists of a vector of vertices (3D points) and vector of triplets defining the 3 vertex indices of each triangle. For each vertex, there can also be a 3D normal and an intensity or RGBA color component. There are two types of triangle representations indexed triangles or separated triangles. In the case of indexed triangles a vertex can be used by several triangles, and in the case of separated triangles a vertex can only be used by a single triangle. In some cases a combination of both representations is also possible. Unless known it might be unclear what representation the mesh has. The representation has consequences in how algorithms perform; an example is the connected components algorithm, with separated triangles none of the triangles share vertex indices so only single connections (1 triangle) can be found. In this case a search radius must be specified to search for nearby vertices.

Functions

clone()
Short description

Returns a duplicated instance of the input mesh. This is a full copy and might be very slow dependent on the mesh size.

Parameters
Name Type Description

inputMesh

CONST_OBJECT Mesh

The mesh to clone.

Return values
Name Type Description

clone

OBJECT Mesh

The new cloned mesh object.

Sample
local clone = Mesh.clone(inputMesh)
create()
Short description

Creates a new empty mesh object

Return values
Name Type Description

newMesh

OBJECT Mesh

The newly created mesh

Sample
local newMesh = Mesh.create()
getTriangleCount()
Short description

Returns the number of triangles in the mesh.

Parameters
Name Type Description

mesh

CONST_OBJECT Mesh

The mesh.

Return values
Name Type Description

triangleCount

INT

The mesh number of triangles.

Sample
local triangleCount = Mesh.getTriangleCount(mesh)
getVertexCount()
Short description

Returns the number of vertices in the mesh.

Parameters
Name Type Description

mesh

CONST_OBJECT Mesh

The mesh.

Return values
Name Type Description

vertexCount

INT

The mesh number of vertices.

Sample
local vertexCount = Mesh.getVertexCount(mesh)
hasColor()
Short description

Check if the mesh contains colors.

Parameters
Name Type Description

mesh

CONST_OBJECT Mesh

The mesh.

Return values
Name Type Description

foundColor

BOOL

True if the mesh contains colors.

Sample
local foundColor = Mesh.hasColor(mesh)
hasIntensity()
Short description

Check if the mesh contains intensities.

Parameters
Name Type Description

mesh

CONST_OBJECT Mesh

The mesh.

Return values
Name Type Description

foundIntensity

BOOL

True if the mesh contains intensities.

Sample
local foundIntensity = Mesh.hasIntensity(mesh)
hasNormals()
Short description

Check if the mesh contains normals.

Parameters
Name Type Description

mesh

CONST_OBJECT Mesh

The mesh.

Return values
Name Type Description

foundNormals

BOOL

True if the mesh contains normals.

Sample
local foundNormals = Mesh.hasNormals(mesh)
hasTextureCoordinates()
Short description

Check if the mesh contains texture coordinates.

Parameters
Name Type Description

mesh

CONST_OBJECT Mesh

The mesh.

Return values
Name Type Description

foundTextureCoordinates

BOOL

True if the mesh contains texture coordinates.

Sample
local foundTextureCoordinates = Mesh.hasTextureCoordinates(mesh)
load()
Short description

Loads a mesh from the specified file path. The format is defined by the file extension: .ply: Polygon File Format .json: JSON .msgpack: MessagePack

See also

File, Object.load

Parameters
Name Type Description

filePath

STRING

The path and name of the file to load the mesh from.

Return values
Name Type Description

mesh

OBJECT Mesh

The mesh object.

Sample
mesh = Mesh.load("private/mesh.ply")
save()
Short description

Saves a mesh to the specified file path. Overwrites the file if it already exists. The format is defined by the file extension: .ply: Polygon File Format (Optional useBinary parameter is supported). .json: JSON (Optional useBinary parameter not supported). .msgpack: MessagePack (Optional useBinary parameter not supported).

See also

File, Object.save

Parameters
Name Type Description

mesh

CONST_OBJECT Mesh

The Mesh object which is saved.

filepath

STRING

The path and name of the file to save the mesh to.

useBinary

BOOL

Optional parameter that can only be used when saving to .ply format. If true write the ply data (except the header) in binary instead of ASCII. Default is true.

Return values
Name Type Description

success

BOOL

Returns true if the mesh has been successfully saved.

Sample
local success = Mesh.save(mesh, "private/mesh.ply", useBinary)
toString()
Short description

Gets a user-friendly string description of the mesh, containing important properties.

Parameters
Name Type Description

mesh

CONST_OBJECT Mesh

The mesh to describe.

Return values
Name Type Description

str

STRING

User-friendly description of the mesh.

Sample
str = Mesh.toString(mesh)

Monitor

Short description

Provides monitoring functionality

Monitor.App

Short description

Provides monitoring access to the status info of an app like app status and memory usage.

Functions

create()
Short description

Creates a new instance.

Parameters
Name Type Description

appName

STRING

The name of the app to monitor.

Return values
Name Type Description

handle

HANDLE

handle to the App-monitor.

Sample
handle = Monitor.App.create("HelloWorld")
getMemoryUsage()
Short description

Get the script interpreter memory usage of the app.

Parameters
Name Type Description

monitorHandle

HANDLE

Handle to the App-monitor.

Return values
Name Type Description

usedBytes

INT

Memory-bytes used by the script interpreter of this app.

Sample
Monitor.App.getMemoryUsage(handle)
getPrivateDataUsage()
Short description

Get the AppData usage of the app.

Parameters
Name Type Description

monitorHandle

HANDLE

Handle to the App-monitor.

Return values
Name Type Description

usedBytes

INT

Bytes in the AppData folder used by this app.

capacityBytes

INT

Total capacity of the AppData folder for all apps in bytes.

appDataUsage

FLOAT

The used bytes of the app in percent of the whole capactiy of the AppData folder.

Sample
Monitor.App.getPrivateDataUsage(handle)
getStatusInfo()
Short description

Get the status of the app.

Parameters
Name Type Description

monitorHandle

HANDLE

Handle to the App-monitor.

Return values
Name Type Description

state

ENUM AppStatus

Status of the app.

additionalInfo

STRING

Additional info to the status of the App. This can be the crash reason in case of a crash.

Sample
Monitor.App.getStatusInfo(handle)

Monitor.CPU

Short description

Provides monitoring access to CPU load in sum and for each core.

Overview

Functions

create()
Short description

Creates a new instance. Can be instantiated multiple times.

Return values
Name Type Description

handle

HANDLE

handle to the CPU-monitor.

Sample
handle = Monitor.CPU.create()
getLoad()
Short description

Get the current load of the CPU.

Parameters
Name Type Description

monitorHandle

HANDLE

Handle to the CPU-monitor.

Return values
Name Type Description

overallLoad

FLOAT

The overall CPU load in percent.

detailedLoad

FLOAT

The load of each CPU core in percent.

Sample
Monitor.CPU.getLoad(handle)

Monitor.Memory

Short description

Provides monitoring access to the RAM memory usage of the device.

Overview

Functions

create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

handle to the Memory-monitor.

Sample
handle = Monitor.Memory.create()
getUsage()
Short description

Get the current memory usage.

Parameters
Name Type Description

monitorHandle

HANDLE

Handle to the Memory-monitor.

Return values
Name Type Description

usedBytes

INT

Currently used bytes.

capacityBytes

INT

Memory capacity in bytes.

memUsage

FLOAT

The memory used in percent of the whole capacity.

Sample
Monitor.Memory.getUsage(handle)

Monitor.Network

Short description

Provides monitoring access to the network interface load of each interface or all interfaces together.

Overview

Functions

create()
Short description

Creates a new instance.

Parameters
Name Type Description

interface

ENUM EthernetInterfaces

The interface to monitor. Use 'ALL' to monitor all interfaces.

Return values
Name Type Description

handle

HANDLE

Handle to the Network-monitor. Will return nil if the interface is not valid, or if no statistics can be loaded.

Sample
Monitor.Network.create("ETH1")
getLoad()
Short description

Get the current network load.

Parameters
Name Type Description

monitorHandle

HANDLE

Handle to the Network-monitor.

Return values
Name Type Description

sentBytesPerSec

INT

Current bytes sent per second.

receivedBytesPerSec

INT

Current bytes received per second.

Sample
Monitor.Network.getLoad(handle)

NTPClient

Short description

Offers access to control the NPTClient of the device. There can be only one NPTClient running on one defined ethernet interface. Also there can be only one controlling the NTPClient, therefore the handle can only be instantiated once. If the handle is destructed, the last NTP configuration keeps active and NTPClient stays running if activated.

Functions

create()
Short description

Creates a handle to the NTPClient. Only one instance can be acquired.

Return values
Name Type Description

handle

HANDLE

Unique handle for the NTPClient. nil if there is already another instance or if the device has no NTP functionality.

Sample
handle = NTPClient.create()
setApplyEnabled()
Short description

Enables or disables the application of the timestamp received by NTP to the system time.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the NTPClient object.

state

BOOL

Set to true to apply NTP time to system time. If set to false the NTP time is just printed to the log.

Sample
NTPClient.setApplyEnabled(handle, false)
setInterface()
Short description

Sets the interface to use for connecting.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the NTPClient object.

ifName

ENUM EthernetInterfaces

One of the available interfaces

Sample
NTPClient.setInterface(handle, "ETH1")
setPeriodicUpdateEnabled()
Short description

Enables or disables periodic NTP requests. Per default, the periodic update is enabled if time source is set to 'NTP'.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the NTPClient object.

state

BOOL

Set to true to request time updates from NTP in 10 minute intervals. If set to false you must trigger requests manually by using startManualRequest().

Sample
NTPClient.setPeriodicUpdateEnabled(handle, true)
setServerAddress()
Short description

Sets the NTP server address.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the NTPClient object.

address

STRING

Address of the NTP server.

Sample
NTPClient.setServerAddress(handle, "192.168.0.1")
setServerPort()
Short description

Sets the NTP server port.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the NTPClient object.

port

INT

Port of the NTP server.

Sample
NTPClient.setServerPort(handle, 12345)
setTimeSource()
Short description

Configures the source of the system time.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the NTPClient object.

source

ENUM TimeSource

System time source.

Return values
Name Type Description

success

BOOL

True if successfully set, false if not.

Sample
success = NTPClient.setTimeSource(handle, "MANUAL")
setTimeout()
Short description

Sets the timeout for NTP requests in milliseconds.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the NTPClient object.

timeout

INT

Timeout in milliseconds.

Sample
NTPClient.setTimeout(handle, 5000)
startManualRequest()
Short description

Trigger a NTP request manually now. TimeSource needs to be set to 'NTP' so that this function works, otherwise returns false. This function does not block until the request is over, it just triggers an asynchronous start of a request.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the NTPClient object.

Return values
Name Type Description

success

BOOL

True if request was successfully triggered, false if not possible because not configured to NTP or internal error.

Sample
success = NTPClient.startManualRequest(handle)

OPCUA

Short description

Provides OPC UA server functionality. OPC UA Overview: The OPC Unified Architecture (UA), released in 2008, is a platform independent service-oriented architecture that integrates all the functionality of the individual OPC Classic specifications into one extensible framework. It is developed by the OPC Foundation. See reference document 1 for more details about the protocol. API Overview: This API implements all the functions that are required to start a OPC UA server. It allows to create nodes of different classes, e.g. variables, objects or methods, and connect them via references to build up a custom information model. Nodes are grouped together into a namespace. A server can have one or more namespaces. The provided functions can be categorized into three groups: 1. Server management and server configuration: OPCUA.Server.* 2. Creating and managing namespaces: OPCUA.Server.Namespace.* 3. Creating, managing and using nodes and references: OPCUA.Server.Node.* According to internal, unofficial tests, this OPC UA CROWN can be used to fulfill the following OPC UA Profiles: - Nano Embedded Device Server Profile (Compliance Test Tool version 1.3.340.380) - SecurityPolicy - None (requires openSSL library) - SecurityPolicy - Basic128Rsa15 (requires openSSL library) - SecurityPolicy - Basic256 (requires openSSL library) - SecurityPolicy - Basic256Sha256 (requires openSSL library) So far, no other profiles are fulfilled. Please note that profile compliance was tested with a reference server implementation using this OPC UA CROWN. Other server implementations using this CROWN need to be tested separately according to the official OPC UA certification procedure in order to officially claim compliance. The server allows the following user token policies: - anonymous - user name / password So far, no other user token policies (e.g., x509, token, …​) are supported. Limitations: - The server does not fulfill the other OPC UA Profiles for servers: Micro Embedded Device Server, Embedded UA Server and Standard UA Server. - loading of NodeSet2 files supported only if server supports the objects and value in the file (e.g., it does not support loading of 2-dimensional values) - If a target device platform does not provide openSSL library, then all security features are disabled. - Only one transport type is supported: UA TCP - UA Secure Conversation - UA Binary. - It is possible to use custom structured data types, however these types must be loaded from XML files. Access to these data types can be done through Value CROWN. - Only one-dimensional arrays are supported. - Unsupported service sets: — NodeManagement Service Set: AddNodes, AddReferences, DeleteNodes, DeleteReferences — View Service Set: RegisterNodes, UnregisterNodes, Query Service Set, QueryFirst, QueryNext — Attribute Service Set: HistoryRead, HistoryUpdate - Unsupported built-in data types: — XmlElement — ExtensionObject (but enumerations are supported) — DataValue — Variant — nested DiagnosticInfos Reference Documents: 1. OPC Unified Architecture Specification, Parts 1-13, https://opcfoundation.org/developer-tools/specifications-unified-architecture

OPCUA.Server

Short description

Provides OPC UA Server functionality.

Functions

create()
Short description

Create a new OPC UA Server instance. Server address space is in a default state (i.e., a pristine NS0). Network communication is not active.

Return values
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server. Currently, it is only possible to create a single instance handle. Fails with return value nil when another instance handle already exists.

Sample
handle = OPCUA.Server.create()
getNamespace()
Short description

Retrieve a namespace from the server

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

index

INT

The index of the namespace to get.

Return values
Name Type Description

namespace

OBJECT OPCUA.Server.Namespace

The requested namespace or nil if the namespace can not be found

loadNodeSet2File()
Short description

Load a NodeSet2 XML file. This method can be called multiple times to load different files. In case of an error during loading (e.g, due to invalid file contents), loading stops when the error is encountered. Consider using resetAddressSpace() to remove partially loaded files from address space.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

fileName

STRING

NodeSet2 XML file to load

Return values
Name Type Description

status

BOOL

True if loaded successfully, false otherwise

resetAddressSpace()
Short description

Reset the OPC UA server. Whole address space is reset to default state (i.e., a pristine NS0). All CROWN instances to existing nodes become invalid. Other settings (e.g., network settings) are not affected by reset. Call reset() only when server is stopped.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

Return values
Name Type Description

success

BOOL

Is true when the OPC UA server has been reset successfully, false if an error occurred.

Sample
success = OPCUA.Server.resetAddressSpace(handle)
setApplicationName()
Short description

Set the name of the application. This name is shown to clients as the name of the server and should describe what the server actually does.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

name

STRING

Name of the application that is shown to clients

Sample
OPCUA.Server.setApplicationName(handle, "MyApplication")
setApplicationURI()
Short description

Set the Application URI. Call to this function is optional. The Application URI of a server represents a globally-unique logical name for a Server within the scope of the network in which it is installed. This identifier should be a fully qualified domain name; however, it may be a GUID or similar construct that ensures global uniqueness. If this function is not called, the following default ApplicationURI urn://sick.com/opc/ua/serial/${DEVICE_PRODUCT}/${SERIAL_NUMBER} is used, where the variable ${DEVICE_PRODUCT} is replaced by the device name and ${SERIAL_NUMBER} is replaced by the serial number. Example for a SIM4000 device: urn://sick.com/opc/ua/serial/SIM4000/12345678

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

uri

STRING

Application URI. Can be chosen freely, but SICK recommends to use the following format: urn://sick.com/opc/ua/app/[product/]unique_identifier. The unique_identifier should not change on device reset.

Sample
OPCUA.Server.setApplicationURI(handle, "urn://sick.com/opc/ua/app/sim/sim4000/my_application_uid")
setConfiguration()
Short description

Set a ServerConfiguration. Please note that server copies the configuration when this function is called.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

config

OBJECT OPCUA.Server.ServerConfiguration

The configuration for the OPC UA Server

setInterface()
Short description

Set the interface on which the server should listen. Call to this function is optional. By default, server listens all interfaces. On multi-homed hosts, it is recommended to bind the server to one specific interface. Otherwise, one OPC UA EndPoint is created for each IP address and the client has to select the right one manually. This function will become deprecated soon. See description of OPCUA CROWN for more details.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

ifName

ENUM EthernetInterfaces

One of the available interfaces

Sample
OPCUA.Server.setInterface(handle, "ETH1")
setNamespaces()
Short description

Set all OPC UA Namespaces the server should use. Please note that his removes any nodes that are neither in standard namespace NS0 nor in the namespaces parameter.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

namespaces

OBJECT OPCUA.Server.Namespace

The Namespace objects the server should use. All Namespaces which have been added previously are removed.

Sample
OPCUA.Server.setNamespaces(handle, {namespace1, namespace2})
setPort()
Short description

Set the port on which the server should listen. Call to this function is optional. By default, port is 4840. This function will become deprecated soon. See description of OPCUA CROWN for more details.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

port

INT

The server port between 1 and 65535.

Sample
OPCUA.Server.setPort(handle, 4840)
start()
Short description

Start the network communication. After a successful start, OPC UA clients can connect to server via network.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

Return values
Name Type Description

success

BOOL

Is true when the OPC UA server has been started successfully, false if an error occurred.

Sample
success = OPCUA.Server.start(handle)
stop()
Short description

Stop the OPC UA server’s network communication.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Server

Return values
Name Type Description

success

BOOL

Is true when the OPC UA server has been stopped successfully, false if an error occurred.

Sample
OPCUA.Server.stop(handle)

OPCUA.Server.EndpointConfiguration

Short description

An EndpointConfiguration consists of (1) a certificate store configuration, (2) a non-empty set of SecurityConfigurations, (3) a boolean flag for enabling application authentication, (4) a reference to an UserTokenDatabase and (5) a bind URL.

Functions

create()
Short description

Create an EndpointConfiguration with default values. Default values are: (1) no certificate store, (2) one SecurityConfiguration with default values, (3) application authentication = disabled, (4) empty UserTokenDatabase (5) interface ="ALL" and (6) port = 4840.

Return values
Name Type Description

config

OBJECT OPCUA.Server.EndpointConfiguration

Configuration with default values

Sample
obj = OPCUA.EndpointConfiguration.create()
enableApplicationAuthentication()
Short description

Enable or disable application authentication.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.EndpointConfiguration

The configuration whose application authentication should be enabled / disabled.

enabled

BOOL

Set to true to enable application authentication.

setCertificateStoreConfiguration()
Short description

Sets the CertificateStoreConfiguration.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.EndpointConfiguration

The configuration whose CertificateStoreConfiguration should be set.

certificateStoreConfiguration

OBJECT [API:DataFormat:]

The CertificateStoreConfiguration to set. Pass nil to indicate that no certificate store should be used.

setInterface()
Short description

Sets the interface to bind the Endpoint to. If interface is set to "ALL", then the Endpoint binds to all network interfaces. In such a case there can only be one EndpointConfiguration in a ServerConfiguration.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.EndpointConfiguration

The configuration whose bind URL should be set.

interface

ENUM EthernetInterfaces

The interface to bind to (e.g., ETH1).

setPort()
Short description

Sets the port to listen to.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.EndpointConfiguration

The configuration whose bind URL should be set.

port

INT

The server port between 1 and 65535.

setSecurityConfigurations()
Short description

Sets the SecurityConfigurations.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.EndpointConfiguration

The configuration whose SecurityConfigurations should be set.

securityConfigurations

OBJECT OPCUA.Server.SecurityConfiguration

Non-empty set of security configurations.

setUserTokenDatabase()
Short description

Sets the UserTokenDatabase. Please note that the behavior of this setter only stores a reference to the UserTokenDatabase. This allows the sharing of one UserTokenDatabase among multiple EndPoints. Consequences are: (1) if a server S is configured to use a UserTokenDatabase instance U and U.addUserPassword("x", "y") is called, then S immediately accepts the user x.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.EndpointConfiguration

The configuration whose UserTokenDatabase should be set.

userTokenDatabase

OBJECT OPCUA.Server.UserTokenDatabase

The UserTokenDatabase to set. Pass nil to indicate that no UserTokenDatabase should be used.

OPCUA.Server.FileCertificateStoreConfiguration

Short description

FileCertificateStoreConfiguration contains information about a file-based certificate store. The only parameter of this certificate store type is the root directory. All other directories should be created with fixed names below root directory. Directory layout: - ${rootDir}/issuer/certs: The issuer directory contains non-trusted issuer / certificate authority (CA) certificates - ${rootDir}/issuer/crl: The issuer CRL directory contains the CRLs of the CA certs from issuer directory. - ${rootDir}/trusted/certs: The trusted directory contains trusted CA certificates and self-signed certificates. - ${rootDir}/trusted/crl: The trusted CRL directory contains the CRLs of the CA certs from trusted directory. Please note that FileCertificateStoreConfiguration only holds the information where to look for certificates. The app developer is responsible for ensuring that the directories exist and contain the required files.

Functions

create()
Short description

Creates a file store configuration with root directory = "."

Return values
Name Type Description

config

OBJECT OPCUA.Server.FileCertificateStoreConfiguration

The created FileCertificateStoreConfiguration instance.

Sample
obj = OPCUA.FileCertificateStoreConfiguration.create()
setRootDirectory()
Short description

Sets the root directory.

Parameters
Name Type Description

database

OBJECT OPCUA.Server.FileCertificateStoreConfiguration

The configuration whose root directory should be set.

rootDir

STRING

The root directory.

OPCUA.Server.Namespace

Short description

Represents a OPC UA namespace. A OPC UA Server can work with one or more user defined namespaces. Namespaces can be added to the server using the function OPCUA.Server.setNamespaces.

Functions

create()
Short description

Create a new OPC UA Namespace instance.

Return values
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Namespace

Sample
handle = OPCUA.Server.Namespace.create()
getNode()
Short description

Retrieve an OPC UA node that is inside the namespace.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Namespace

idType

ENUM NodeIDType

Type of the ID

id

AUTO

The ID of the Node to get

Return values
Name Type Description

node

OBJECT OPCUA.Server.Node

The requested node or nil if the node can not be found

Sample
local node = OPCUA.Server.Namespace.getNode(handle, "STRING", "MySimpleVariableNode")
getNodeFromStandardNamespace()
Short description

Retrieve a node that is part of the standard namespace NS0. The available Node IDs are listed in the OPC Unified Architecture Specification, Part 6: Mappings, Annex B: OPC UA Nodeset.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Namespace

idType

ENUM NodeIDType

Type of the ID

id

AUTO

The ID of the Node to get

Return values
Name Type Description

node

OBJECT OPCUA.Server.Node

The requested node or nil if the node can not be found

Sample
local node = OPCUA.Server.Namespace.getNodeFromStandardNamespace(handle, "NUMERIC", 5)
setIndex()
Short description

Sets the index of the namespace. Calling this function. By default, namespace indices are assigned automatically in the order of namespace creation, starting with index 2.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Namespace

index

INT

The namespace index to use. Must not be in use by any other namespace.

url

STRING

URL that identifies the namespace, is shown to clients for a better understanding of the namespace index. Should start with urn://. If not provided, default is device_product/namespace_index_as_string

Sample
OPCUA.Server.Namespace.setIndex(handle, 3)
setNodes()
Short description

Set all nodes that belong to this namespace.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Namespace

nodes

OBJECT OPCUA.Server.Node

All nodes that should belong to this namespace, including the root node.

Sample
OPCUA.Server.Namespace.setNodes(handle, {node1, node2})
setRootNode()
Short description

Sets the root node of the namespace.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Namespace

root

OBJECT OPCUA.Server.Node

The root node. It is recommended to use a folder node as root

suspensionFolder

OBJECT OPCUA.Server.Node

Optional. The node (folder) that is the parent node of root. Default is the global root node of the OPC UA default namespace

Sample
OPCUA.Server.Namespace.setRootNode(handle, rootNode)

OPCUA.Server.Node

Short description

Represents a single node in the address space of a OPC UA server. Some node types (of type "Variable" and "VariableType") contain values. These can be accessed via getValue(), setValue() and getValueHandle(). For more information on value handling see OPCUA.Server.Value CROWN.

Functions

addReference()
Short description

Create a reference from this node to another node. An inverse reference from the target node to this node is created automatically, if possible. Example: When creating a reference from folderNode to otherNode with reference type "Organizes", otherNode automatically gets an inverse reference of type "OrganizedBy" to folderNode.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

type

ENUM ReferenceType

Type of the reference between this node and the target node

other

OBJECT OPCUA.Server.Node

The target node to which the reference points

Sample
OPCUA.Server.Node.addReference(folderHandle, "ORGANIZES", simpleVariable)
callMethod()
Short description

Call the method on the node

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

parameters

OBJECT OPCUA.Server.Value

The parameters that should be used for the call. Might be omitted (nil) if there are no parameters.

Return values
Name Type Description

returnValues

OBJECT OPCUA.Server.Value

The return values of the call. Might be omitted (nil) if there are no return values.

Sample
OPCUA.Server.Node.callMethod(handle, {paramValueHandle1, paramValueHandle2}) -- This method takes two parameters
create()
Short description

Creates a new OPC UA node.

Parameters
Name Type Description

class

ENUM NodeClass

Class of the node

Return values
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

Sample
handle = OPCUA.Server.Node.create("VARIABLE")
createEventParameters()
Short description

Create the parameters for an event; only works for event type nodes

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

Return values
Name Type Description

parameters

OBJECT OPCUA.Server.Value

The parameters of the call. Might be omitted (nil) if there are no parameters.

Sample
OPCUA.Server.Node.createEventParameters(handle)
createMethodParameters()
Short description

Create the default parameters for a method

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

Return values
Name Type Description

parameters

OBJECT OPCUA.Server.Value

The return values of the call. Might be omitted (nil) if there are no return values.

Sample
OPCUA.Server.Node.createMethodParameters(handle)
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

getValue()
Short description

Gets the current value of the OPC UA node. Only works if NodeClass is VARIABLE or OBJECT.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

Return values
Name Type Description

value

AUTO

The value of the node

Sample
local value = OPCUA.Server.Node.getValue(handle)
getValueHandle()
Short description

Gets the current value (a handle for the value) of the OPC UA node. Only works if NodeClass is VARIABLE or VARIABLE_TYPE.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

Return values
Name Type Description

value

HANDLE

The value of the node

Sample
local value = OPCUA.Server.Node.getValueHandle(handle)
notifyEvent()
Short description

Let the node notify the given event if it is a source of this event. (All Notifier nodes are informed)

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

fireEventType

OBJECT OPCUA.Server.Node

Type of the event to be notified (instance of EventType (ObjectType))

severity

ENUM EventSeverity

How severe is the event to be notified

message

STRING

Message to be transferred (human readable)

parameters

OBJECT OPCUA.Server.Node

The additional parameters of the event

Sample
OPCUA.Server.Node.notifyEvent(handle, eventTypeNode, "MEDIUM", "demoEvent occurred.")
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

registerCallbacks()
Short description

Register functions that should be called to get or set the value of the OPC UA node. The getter function has the following signature: no input parameters. Getter returns a value of type OPCUA.Server.Value. For legacy compatibility it is still possible to return builtin values. It is strongly recommended to return OPCUA.Server.Value, because legacy behaviour is deprecated and will be removed soon. The setter function has the following signature: one OPCUA.Server.Value value as input parameter. Setter returns true if value was set successful, false otherwise. Please note that OPCUA.Server.Value is used to enable setting of complex types (e.g., structures or unions). There is not guarantee on the number of getter/setter callback invocations by internal mechanism. In general, lua callbacks should not be used for runtime performace crtical features.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

getter

STRING

Name of the Getter function

setter

STRING

Name of the Setter function. The function must return a bool value that indicates success (true) or failure (false)

Sample
OPCUA.Server.Node.registerCallbacks(handle, getter, setter)
setAccessLevel()
Short description

Function to set access level to values of VARIABLE nodes.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

accessLevel

ENUM AccessLevel

Access level for the variable

Sample
OPCUA.Server.Node.setAccessLevel(handle, "READ_WRITE")
setArrayDimensions()
Short description

Specify the size of an array. For each dimension of the array, a corresponding value in the list specifies the length of the dimension. Currently, only one-dimensional arrays are supported. A data type must be set before setting the dimensions.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

dimensions

INT

The dimensions with specified length. If the first dimension is zero, scalar value is used.

Sample
OPCUA.Server.Node.setArrayDimensions(handle, {3})
setBrowseName()
Short description

Sets the name of the node that is used for browsing.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

browseName

STRING

The browse name to use

Sample
OPCUA.Server.Node.setBrowseName(handle, "MySimpleVariableNode")
setDataType()
Short description

Set the data type of the OPC UA node to one of the standard node types. Arbitrary types can be set by using the function setDataTypeByNode instead. Only applies to nodes of type VARIABLE or VARIABLE_TYPE.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

type

ENUM DataType

The type of this node

Sample
OPCUA.Server.Node.setDataType(handle, "UINT32")
setDataTypeByNode()
Short description

Set the type of the OPC UA node. For standard node types use the function setDataType instead. Only applies to nodes of type VARIABLE or VARIABLE_TYPE.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

type

OBJECT OPCUA.Server.Node

The OPC UA Node which represents the type

Sample
OPCUA.Server.Node.setDataTypeByNode(handle, typeNode)
setDescription()
Short description

Sets the description (explaining text) of the node. Optional. If not called, BrowseName is used.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

description

STRING

The description text

Sample
OPCUA.Server.Node.setDescription(handle, "Description of this node.")
setDisplayName()
Short description

Sets the name of the node that is used for displaying at clients. Optional. If not called, BrowseName is used.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

displayName

STRING

The display name to use

Sample
OPCUA.Server.Node.setDisplayName(handle, "MySimpleVariableNode")
setEnumChoices()
Short description

Function to an enum choice to a DATA_TYPE node. Will make the node automatically sub node of Enumeration type (i=29). The same name must not be given multiple times.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

value

STRING

Name of the choice to add

Sample
OPCUA.Server.Node.setEnumChoices(handle, {"NAME OF THE CHOICE", "NAME OF CHOICE 2"})
setID()
Short description

Sets the ID of the OPC UA node.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

type

ENUM NodeIDType

Which type of ID to use

id

AUTO

The ID. Must be unique within a namespace

Sample
OPCUA.Server.Node.setID(handle, "STRING", "MySimpleVariableNode")
setMethodBehavior()
Short description

This function is used to register a callback that is executed when a client calls the method. Optionally, it is possible to set one or more return values and parameters for the method.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

callback

STRING

Function name to call when client calls the method. Is optional, a callback is not needed if this METHOD node is part of an OBJECT_TYPE.

returnValues

ENUM DataType

Specifies number and data type of the method return values

parameters

ENUM DataType

Specifies number and data type of method parameters

Sample
OPCUA.Server.Node.setMethodBehavior(handle, "callbackFunctionName", {"BOOL"}, {"INT32"}) -- This method takes one INT32 as argument and returns BOOL
setTypeDefinition()
Short description

Set the type of the OPC UA node to one of the standard node types. Arbitrary types can be set by using the function setTypeDefinitionByNode instead.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

type

ENUM NodeType

The type of this node

Sample
OPCUA.Server.Node.setTypeDefinition(handle, "FOLDER_TYPE")
setTypeDefinitionByNode()
Short description

Set the type of the OPC UA node. For standard node types, the function setTypeDefinition can be used instead.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

type

OBJECT OPCUA.Server.Node

The OPC UA Node which represents the type

Sample
OPCUA.Server.Node.setTypeDefinitionByNode(handle, typeNode)
setValue()
Short description

Sets the current value of the OPC UA node. Only works if NodeClass is VARIABLE or OBJECT.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

value

AUTO

The new value for the node

Sample
OPCUA.Server.Node.setValue(handle, 123)

Events

OnWrite
Short description

This event is thrown when a Node of type VARIABLE is written by a OPC UA client. It is not thrown when a Node is written internally via API function OPCUA.Server.Node.setValue(). If the write does not change the value, the event is thrown anyway.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Node

OPCUA.Server.SecurityConfiguration

Short description

A security configuration consists of (1) a set of credentials (a certificate and a private key representing the server), (2) a SecurityPolicy, (3) a set of MessageSecurityModes and (4) a set of UserTokenPolicies. Each endpoint has one or more SecurityConfigurations.

Functions

create()
Short description

Creates a SecurityConfiguration with default settings. Default settings are: (1) UserTokenPolicy = ANONYMOUS, (2) MessageSecurityMode = NONE, (3) no server credentials and (4) SecurityPolicy = NONE

Return values
Name Type Description

config

OBJECT OPCUA.Server.SecurityConfiguration

Default SecurityConfiguration instance

Sample
handle = OPCUA.Server.SecurityConfiguration.create()
setMessageSecurityModes()
Short description

Sets a set of MessageSecurityModes.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.SecurityConfiguration

The configuration instance whose MessageSecurityModes should be set

modes

ENUM MessageSecurityMode

Non-empty, duplicate-free list of MessageSecurityModes

setSecurityPolicy()
Short description

Sets the security policy

Parameters
Name Type Description

config

OBJECT OPCUA.Server.SecurityConfiguration

The configuration instance whose SecurityPolicy should be set

securityPolicy

ENUM SecurityPolicy

The SecurityPolicy to use

setServerCredentials()
Short description

Sets the server credentials. The certificate and the private key have to match. Either specify both or none. Specify none in case that no server credentials should be used (i.e., no signing and/or encryption is used). Parameters certificate and privateKey are interpreted in the context of the used certificate store. When used together with a FileCertificateStoreConfiguration, certificate and privateKey parameters are interpreted as files. However, future releases might introduce different types of key stores (e.g., remote certificate stores or hardware key stores). In that case, parameters certificate and privateKey specify something different than file names.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.SecurityConfiguration

The configuration instance whose server credentials should be set

certificate

STRING

When using FileCertificateStoreConfiguration, this parameter specifies the name of the file where the certificate to be used for the server is stored in DER format. Use empty string ("") if no certificate shall be used.

privateKey

STRING

When using FileCertificateStoreConfiguration, this parameter specifies the name of the file where the private key to be used for the server is stored in PEM format. Use empty string ("") if no private key shall be used.

setUserTokenPolicies()
Short description

Sets a set of UserTokenPolicies.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.SecurityConfiguration

The configuration instance whose UserTokenPolicies should be set

policies

ENUM UserTokenPolicy

Non-empty, duplicate-free list of UserTokenPolicies

OPCUA.Server.ServerConfiguration

Short description

Configuration of an OPC UA server. Default server configuration has (1) a list with one EndpointConfiguration set to default values.

Functions

create()
Short description

Creates a server configuration with default parameters.

Return values
Name Type Description

config

OBJECT OPCUA.Server.ServerConfiguration

The created configuration.

Sample
obj = OPCUA.Server.ServerConfiguration.create()
setEndpointConfigurations()
Short description

Sets the endpoint configurations.

Parameters
Name Type Description

config

OBJECT OPCUA.Server.ServerConfiguration

The ServerConfigration whose EndpointConfigurations should be set.

endpointConfigurations

OBJECT OPCUA.Server.EndpointConfiguration

Non-empty list of EndpointConfigurations.

OPCUA.Server.UserTokenDatabase

Short description

UserTokenDatabase is used for maintaining a set of user credentials that can be used to authenticate at an OPC UA Endpoint. UserTokenDatabases are set to EndpointConfigurations in a reference-like manner. This was done to allow several endpoints to use the same UserTokenDatabase. When endpoints are created from a ServerConfiguration, server starts to uses the references UserTokenDatabase(s). As consequences, any changes to a user database apply directly to the (running) server.

Functions

addUserPassword()
Short description

Add a user with a password to the database.

Parameters
Name Type Description

database

OBJECT OPCUA.Server.UserTokenDatabase

The database to add the user to.

userName

STRING

Name of the user.

password

STRING

Password of the user

create()
Short description

Creates an empty database.

Return values
Name Type Description

database

OBJECT OPCUA.Server.UserTokenDatabase

The created database.

Sample
obj = OPCUA.UserTokenDatabase.create()

OPCUA.Server.Value

Short description

The Value crown allows to create, access and modify OPC UA values as specified in OPC UA specification parts 3, 4 and 6. Values can be (1) used to set or get the value of OPC UA variable or variable type nodes, (2) used as parameters to OPC UA method calls, (3) or used as parameters to OPC UA events. Values can be (1) simple, built-in OPC UA data types (e.g., int16, string, an enumeration value), (2) OPC UA structures containing (optional) named fields, (3) OPC UA unions, (4) or arrays of the aforementioned value types. Fields of a Value are addressed by paths. The empty path "" addresses the current element. All OPC UA built-in data types are accessed through using an empty path. In structures and unions, fields have unique names. They can be addressed by their names. Nested fields are separated by dots ("."). Array members are addressed by zero-based indices in brackets ([]).

Functions

getActiveUnionField()
Short description

Get the field that is currently active at the union

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Value

path

STRING

The path of the member

Return values
Name Type Description

field

ENUM UnionField

The field that is currently set active

Sample
OPCUA.Server.Value.getActiveUnionField(handle, "")
getArrayLength()
Short description

Get the current element count of an array

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Value

path

STRING

The path of the member to be resized

Return values
Name Type Description

length

INT

The current element count of the array or -1 if the selected path is not an array or NULL

Sample
OPCUA.Server.Value.getArrayLength(handle, "")
getOptionalFieldState()
Short description

Get the state of an optional structure field

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Value

path

STRING

The path of the member to be enabled/ disable

Return values
Name Type Description

state

AUTO

The current state of the field, or nil if field is non-optional.

Sample
OPCUA.Server.Value.getOptionalFieldState(handle, "")
getValue()
Short description

Get the builtin value(s) contained in the Value instance.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Value

path

STRING

The path of the member

Return values
Name Type Description

value

AUTO

The builtin value

Sample
local value = OPCUA.Server.Value.getValue(handle, "some_field.an_integer")
resizeArray()
Short description

Set the new element count of an array

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Value

newSize

INT

The new element count of the array

path

STRING

The path of the member

Sample
OPCUA.Server.Value.resizeArray(handle, 10, "")
setArrayToNull()
Short description

Set an array to NULL. (In OPC UA, array can have length 0 OR be null.)

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Value

path

STRING

The path of the member to be nulled

Sample
OPCUA.Server.Value.setArrayToNull(handle, "")
setOptionalFieldState()
Short description

Enable / disable an optional field of a structure

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Value

state

ENUM OptionalFieldState

The new field state

path

STRING

The path of the member to be enabled/ disabled

Sample
OPCUA.Server.Value.setOptionalFieldState(handle, "ENABLED", "")
setValue()
Short description

Sets the builtin value of the Value instance.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Value

value

AUTO

The builtin value

path

STRING

The path of the member

Sample
OPCUA.Server.Value.setValue(handle, 123, "some_field.an_integer")
switchUnionField()
Short description

Set the field of a union that is active

Parameters
Name Type Description

handle

HANDLE

The instance handle of the OPC UA Value

field

ENUM UnionField

The field to be set active

path

STRING

The path of the member to be activated

Sample
OPCUA.Server.Value.switchUnionField(handle, "FIELD_1", "")

Object

Short description

Provides functionality to work on object datatypes. Persistence is one of the main features. Currently supported data format: JSON (file extension ".json") and MessagePack (file extension .msgpack)

Functions

clone()
Short description

Creates a full deep copy clone of the provided object/handle. Can fail if the object/handle does not support cloning.

Parameters
Name Type Description

obj

CONST_AUTO

The object/handle to clone

Return values
Name Type Description

cloneObj

AUTO

The cloned object/handle. Nil if clone was not possible or not successful.

deserialize()
Short description

De-Serializes an object from a byte array

Parameters
Name Type Description

serializedData

BINARY

The serialized data

dataFormat

ENUM DataFormat

Data format specification

Return values
Name Type Description

obj

AUTO

A valid object/handle (or multiple of them) in case of success, no value in case of error

Sample
obj = Object.deserialize(data, "JSON")
getType()
Short description

Returns the type name of an object/handle which is the CROWN name assigned to the object

Parameters
Name Type Description

obj

CONST_AUTO

The object/handle to get the type from

Return values
Name Type Description

crownName

STRING

The name of the CROWN the object is assigned to

load()
Short description

Loads an object/handle content from a file. When the type parameter is not passed, the data format is guessed from the file extension.

Parameters
Name Type Description

fileName

STRING

The file where the data should read from

dataFormat

ENUM DataFormat

Optional data format specification. If omitted, it is guessed from the file name extension

Return values
Name Type Description

obj

AUTO

A valid object/handle (or multiple of them) in case of success, no value in case of error

Sample
object = Object.load("private/FileContent.json")
save()
Short description

Saves an object content to a file. If the data type enumeration is not passed as argument, the file extension is used to guess the data format.

Parameters
Name Type Description

obj

CONST_AUTO

The object/handle(s) to be saved. Only objects/handle types are supported. Saving of handles is reserved for future use.

fileName

STRING

The file where the data should be written to

dataFormat

ENUM DataFormat

Optional data format specification. If omitted, it is guessed from the file name extension

Return values
Name Type Description

success

BOOL

true when saving succeeded, false when there was an error. In case of errors, please look at the console for error information

Sample
success = Object.save(data, "private/FileContent.json")
serialize()
Short description

Serializes an object to a byte array

Parameters
Name Type Description

obj

CONST_AUTO

The object/handle(s) to be serialized. Only objects/handle types are supported. In case of handles, the configuration data is saved which was passed at the creation of the handle (if supported by the handle)

dataFormat

ENUM DataFormat

Data format specification

Return values
Name Type Description

serializedData

BINARY

The serialized data in case of success, no data otherwise

Sample
buf = Object.serialize(data, "JSON")
toConst()
Short description

Return the provided object explicitly as const object. This is useful to guarantee further const usage of the object. The input object is not touched and stays non-const.

Parameters
Name Type Description

obj

CONST_OBJECT [API:DataFormat:]

The object to return as const

Return values
Name Type Description

constObj

CONST_OBJECT [API:DataFormat:]

The same object but as const

Parameters

Short description

Provides access to parameters of the current application and the device parameters. This CROWN implements the AppSpace Parameters component. Read more about Parameters in the AppSpace documentation. Parameters could be basic types (int, bool, …​) which can be accessed over "Parameters.get" and "Parameters.set" in this case. Parameters could be complex types (array, struct, …​) which can be accessed over "Parameters.getNode" and "Parameters.setNode" in this case. Complex parameters are represented as "Parameters.Node" object and can be accessed and navigated over its functions.

Functions

apply()
Short description

Parameters of the device are not automatically activated when calling the Parameters.set/setNode function. This function has to be called after using the "Parameters.set" or "Parameters.setNode" function so that they are applied on the device. Please note that the parameters are not directly updated if this function returns. The event "Parameters.OnParametersChanged" is triggered after calling this function when the parameters are updated to inform the device and other applications.

Sample
Parameters.apply()
get()
Short description

Returns the value of the specified parameter. Please note that all parameter repositories of the device are considered, not only application parameters. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If read fails function returns nothing. It can fail if the parameter is not existing or it has a complex type. If it has a complex type please use the "Parameters.getNode" function.

Parameters
Name Type Description

varName

STRING

The name or path of the parameter to be read

Return values
Name Type Description

varValue

AUTO

The value(s) of the parameter. Nil if parameter does not exist or type not possible. The type which is returned depends on the value of the parameter.

Sample
-- Usage possibilities:
local theParam = Parameters.get("LocationName") -- single string parameter get
local subValue = Parameters.get("MyParameter/subValue") -- get over xpath
local arrayValue = Parameters.get("MyArray[0]") -- get first array value
getNode()
Short description

Returns a copy of the parameter as "Parameters.Node" to navigate in the parameter structure. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The return object is a copy of the current parameter values. If it is changed, the "Parameters.setNode" function has to be called with the object.

Parameters
Name Type Description

varName

STRING

The name or path of the parameter to be written

Return values
Name Type Description

nodeObjectCopy

OBJECT Parameters.Node

The copy of the node object of the parameter or nil if parameter does not exist

Sample
-- Get a parameter node, get all member nodes of it and print how much nodes the parameter has:
local theNode = Parameters.getNode("MyComplexParameter")
local subNodes = Parameters.Node.getNode(theNode)
print("Number of subnodes in MyComplexParameter: " .. ##subNodes)
loadAllDefaults()
Short description

Loads the default values of all parameters of the device. It affects all parameters of all apps as well as the parameters of the device. Concretely this function sets all parameters to factory defaults. This function does NOT do a save permanent.

Sample
Parameters.loadAllDefaults()
loadBlockDefaults()
Short description

Loads the default values of all app parameters in the specified block of all loaded parameter files. This function does NOT work with device parameters, only with app parameters.

Parameters
Name Type Description

blockName

STRING

The name of the block in the app parameters file(s)

Return values
Name Type Description

success

BOOL

True if successfully restored the default values for the block(s). False on error or block does not exist in no parameters file

loadDefault()
Short description

Loads the default value of the specified app parameter. This function does NOT work with device parameters, only with app parameters.

Parameters
Name Type Description

varName

STRING

The name or path of the parameter to be load the default value

Return values
Name Type Description

success

BOOL

True if successfully restored the default value- False on error or block does not exist

Sample
Parameters.loadDefault("MyParameter")
loadPermanent()
Short description

This function restores all current permanent stored values of all application and device parameters. Per default a permanent load is done automatically on bootup of the device. This function blocks until the restoring is done. There is no apply on the parameters done and no OnParametersChanged event thrown. The user has to call the apply() function manually.

Sample
Parameters.loadPermanent()
savePermanent()
Short description

This function stores the current parameter values of all applications and the device permanently. The values of the permanent stored parameters are automatically loaded on bootup of the device again. This function blocks until the storing is done.

Sample
Parameters.savePermanent()
set()
Short description

Sets the value of the specified parameter. Please note that all parameter repositories of the device are considered, not only application parameters. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If set fails the function returns false. Parameter values are directly updated and CoLa events are directly fired (also if the values are identical), but device parameters are not directly activated. Therefore if device parameters have been changed, the "Parameters.apply" function needs to be called so that they get active.

Parameters
Name Type Description

varName

STRING

The name or path of the parameter to be written

varValue

AUTO

The value(s) of the parameter.

Return values
Name Type Description

success

BOOL

True if successfully set. False if parameter does not exist or type does not match the parameter declaration

Sample
-- Usage possibilities:
local bSuccess = Parameters.set("LocationName", "Mydevice") -- set single string parameter value
local bSuccess = Parameters.set("MyParameter/memberString", "stringValue") -- set sub parameter value
local bSuccess = Parameters.set("MyArray[0]", 123) -- set first array value
setNode()
Short description

Sets the value of the specified parameters as "Parameters.Node". This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The specified node content and structure has to match the parameter declaration. A matching node for a parameter can be get over "Parameters.getNode". If set fails the function returns false. Parameter values are directly updated and CoLa events are directly fired (also if the values are identical), but device parameters are not directly activated. Therefore if device parameters have been changed, the "Parameters.apply" function needs to be called so that they get active.

Parameters
Name Type Description

varName

STRING

The name or path of the parameter to be written

nodeObject

CONST_OBJECT Parameters.Node

The node object with the new values. The node structure has to match the parameter

Return values
Name Type Description

success

BOOL

True if successfully set. False if parameter does not exist or node structure does not match the parameter declaration

Sample
-- Get a parameter node, modify it and write the whole parameter:
local theNode = Parameters.getNode("MyComplexParameter")
Parameters.Node.set(theNode, "memberString", "stringValue")
Parameters.setNode("MyComplexParameter", theNode)

Events

OnAllDefaultsLoaded
Short description

This event is notified when the all parameter default values were loaded. A all-defaults-loading can be triggered by the API function "Parameters.loadAllDefaults" and over the command interface.

OnParametersChanged
Short description

This event is notified when the parameters of the application or the device might have changed. There is no information if parameters are really changed or which parameters are changed. This event might also be thrown even when were no parameters changed at all. The user has to read its parameters using the "Parameters.get" function and detect himself if it has changed.

OnParametersLoaded
Short description

This event is notified when the parameters were restored from permanent storage. A load permanent is triggered by the API function "Parameters.loadPermanent" or over the command interface.

OnParametersSaved
Short description

This event is notified when the parameters were stored permanently. A save permanent is triggered by the API function "Parameters.savePermanent" or over the command interface.

Parameters.Listener

Short description

Provides functionality to register for or poll changes of parameter values. One listener could listen to several parameters by using the add()-function multiple times. The user could register for an OnChanged-event to get every write to a listened parameter. Alternatively it could only use isChanged()- and clearChanged()-functions and e.g. call them during 'Engine.OnStarted' event handling. This functionality does NOT work with device parameters, only with app parameters.

Functions

add()
Short description

Adds a parameter name to listen to

Parameters
Name Type Description

handle

HANDLE

The instance handle of Parameters.Listener

paramName

STRING

The name of the parameter to listen to

Return values
Name Type Description

success

BOOL

True if successfully added. False if not possible or parameter does not exist

Sample
Parameters.Listener.add(handle, "MyParameterName")
clearChanged()
Short description

Clears a changed state manually.

Parameters
Name Type Description

handle

HANDLE

The instance handle of Parameters.Listener

Sample
Parameters.Listener.clearChanged(handle)
create()
Short description

Creates a new listener instance. The listener stays active as long as this instance exists.

Return values
Name Type Description

handle

HANDLE

The new Parameters.Listener instance

Sample
handle = Parameters.Listener.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

isChanged()
Short description

Polls the current changed state. State needs to be reset manually using the clearChanged()-function.

Parameters
Name Type Description

handle

HANDLE

The instance handle of Parameters.Listener

Return values
Name Type Description

changed

BOOL

True if the parameters was

Sample
local bIsChanged = Parameters.Listener.isChanged(handle)
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

Events

OnChanged
Short description

Is thrown if the value of the parameters has changed or is written with same value

Parameters
Name Type Description

handle

HANDLE

The instance handle of Parameters.Listener

Sample
Parameters.Listener.register(handle, "OnChanged", "handleChanged")

Parameters.Node

Short description

A "Parameters.Node" object represents a parameter composition or one leaf of it. If can be used to navigate in the tree of the complex parameter to access or modify values. A node cannot be created by this CROWN, but it is returned e.g. from "Parameters.getNode".

Functions

get()
Short description

Gets the single value or all values of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If the accessed leaf is a struct or array, then use the getNode()-function instead.

Parameters
Name Type Description

nodeObject

CONST_OBJECT Parameters.Node

The instance of the object to use

relativePath

STRING

The name or relativePath to access. Nil if accessing this node

Return values
Name Type Description

varValue

AUTO

The value(s) of the parameter. Nil if parameter does not exist or type not possible. The type which is returned depends on the value of the parameter.

Sample
-- Usage possibilities:
local singleValue = Parameters.Node.get(node) -- if the node is a single value get it
local singleSubValue = Parameters.Node.get(node, "subValue") -- get the member value "subValue" of this node if it is a struct
local arraySubValue = Parameters.Node.get(node, "subArray") -- get all the member array values of member "subArray" if it is a struct
local arrayValue = Parameters.Node.get(node, "[0]") -- get the first index value of an array node. Index number is interpreted as hex-number.
local singleSubArrayValue = Parameters.Node.get(node, "subMember/subArray[0]") -- get the first value of the subArray which is member of the subMember struct. Index number is interpreted as hex-number.
getAllNodes()
Short description

Gets copies of all children nodes of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. It is possible to get the children of structs and arrays.

Parameters
Name Type Description

nodeObject

CONST_OBJECT Parameters.Node

The instance of the object to use

relativePath

STRING

The name or relativePath to access. Nil if accessing this node

Return values
Name Type Description

nodeObjectCopies

OBJECT Parameters.Node

The copies of the node objects of the parameter or nil if parameter does not exist

Sample
-- Usage possibilities:
local subNodes = Parameters.Node.getAllNodes(node) -- get all sub nodes of the node
local subNodes = Parameters.Node.getAllNodes(node, "subMember") -- get all member nodes of a sub struct
getArraySize()
Short description

Returns the size if this node is an array. If it is a flexible array, then the current size is returned.

Parameters
Name Type Description

nodeObject

CONST_OBJECT Parameters.Node

The instance of the object to use

relativePath

STRING

The name or relativePath to access. Nil if accessing this node

Return values
Name Type Description

size

INT

The current size of the array. Nil if it is not an array

Sample
local arrSize = Parameters.Node.getArraySize(node)
getNode()
Short description

Gets a copy of a single node of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers.

Parameters
Name Type Description

nodeObject

CONST_OBJECT Parameters.Node

The instance of the object to use

relativePath

STRING

The name or relativePath to access. Nil if accessing this node

Return values
Name Type Description

nodeObjectCopy

OBJECT Parameters.Node

The copy of the node object of the parameter or nil if parameter does not exist

Sample
-- Usage possibilities:
local subNode = Parameters.Node.getNode(node, "childName") -- get one member node named "childName"
local subArraynode = Parameters.Node.getNode(node, "subMember/subArray[0]") -- get the first value of the subArray which is member of subMember struct. Index number is interpreted as hex-number.
set()
Short description

Sets the single value or all values of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If set fails the function returns false.

Parameters
Name Type Description

nodeObject

OBJECT Parameters.Node

The instance of the object to use

varValue

AUTO

The value(s) of the parameter. Nil if parameter does not exist or type not possible. The type has to match the declaration of the parameter.

relativePath

STRING

The name or relativePath to access. Nil if accessing this node

Return values
Name Type Description

success

BOOL

True if successfully set. False if parameter does not exist or type does not match the parameter declaration

Sample
-- Usage possibilities:
local bSuccess = Parameters.Node.set(node, "stringValue") -- Set a single value to this node if it is a string parameter node
local bSuccess = Parameters.Node.set(node, "stringValue", "memberString") -- Set a value to one member of this node if it is a struct
setAllNodes()
Short description

Sets all specified nodes as children to this node or to a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The specified node content and structure has to match the current node parameter declaration. It is possible to set the children of structs and arrays. If set fails the function returns false. This node can be inconsistent in case of fail.

Parameters
Name Type Description

nodeObject

OBJECT Parameters.Node

The instance of the object to use

valueObject

CONST_OBJECT Parameters.Node

The node objects with the new values. The node structure has to match the parameter. Values are copied to the nodeObject.

relativePath

STRING

The name or relativePath to access. Nil if accessing this node

Return values
Name Type Description

success

BOOL

True if successfully set. False if parameter does not exist or node structure does not match the parameter declaration

Sample
-- Usage possibilities:
local bSuccess = Parameters.Node.setAllNodes(node, nodeVector) -- set the nodes of the vector to this one
setArraySize()
Short description

Sets the size of this node if it is an array and the size or the array is declared as flexible

Parameters
Name Type Description

nodeObject

OBJECT Parameters.Node

The instance of the object to use

size

INT

The new size of the array

relativePath

STRING

The name or relativePath to access. Nil if accessing this node

Return values
Name Type Description

success

BOOL

True if successful set. False if array size does not match the parameter declaration.

Sample
Parameters.Node.setArraySize(node, 5)
setNode()
Short description

Sets the single node of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The specified node content and structure has to match the current node parameter declaration. If set fails the function returns false.

Parameters
Name Type Description

nodeObject

OBJECT Parameters.Node

The instance of the object to use

valueObject

CONST_OBJECT Parameters.Node

The node object with the new values. The node structure has to match the parameter. Values are copied to the nodeObject.

relativePath

STRING

The name or relativePath to access. Nil if accessing this node

Return values
Name Type Description

success

BOOL

True if successfully set. False if parameter does not exist or node structure does not match the parameter declaration

Sample
-- Usage possibilities:
local bSuccess = Parameters.Node.setNode(node, otherNode) -- sets the values of another node to this one

Parameters.Validator

Short description

Provides functionality to hook in to parameter writes to decide if a write is allowed or not. One validator could validate several parameters by using the add()-function multiple times. The validator function can be set using the setCallback()-function. See description of the setCallback()-function for details about the callback implementation. This functionality does NOT work with device parameters, only with app parameters.

Functions

add()
Short description

Adds a parameter name to validate

Parameters
Name Type Description

handle

HANDLE

The instance handle of Parameters.Validator

paramName

STRING

The name of the parameter to validate

Return values
Name Type Description

success

BOOL

True if successfully added. False if not possible or parameter does not exist

Sample
Parameters.Validator.add(handle, "MyParameterName")
create()
Short description

Creates a new validator instance. The validator stays active as long as this instance exists.

Return values
Name Type Description

handle

HANDLE

The new Parameters.Validator instance

Sample
handle = Parameters.Validator.create()
handle:add("MyParam")
function callback(paramName, paramNode)
  -- Use paramName and paramNode to decide if return true/false
  return bOk
end
handle:setCallback(handle, callback)
setCallback()
Short description

Sets the validator callback function which is called upon writes to the added parameters. The function gets called with two parameters: The parameter name and a Parameters.Node const-object containing the value which wants to be written. It is not guaranteed that the second parameter with the value object is available. If the parameter write is done over communication interfaces, it is present, but if the write is done using Parameters.set()-function, it is not available. The function gets called in blocking mode and the current parameter-write is blocked until the function returns. If the function returns true, the parameter-write is done. If false, then there is an error thrown on the CoLa command interface with number 0x4 (condition wrong)

Parameters
Name Type Description

handle

HANDLE

The instance handle of Parameters.Validator

funcCallback

STRING

The function name to be called for validation. Needs to have a specific signature, read more about in the function documentation.

Sample
function callback(paramName, paramNode)
  -- get values from "paramNode" using Parameters.Node-functions
  -- if writing should be done, return true. Otherwise return false.
  return bOk
end
Parameters.Validator.setCallback(handle, callback)

Point

Short description

Represents a point/vector in 2D or 3D

Functions

add()
Short description

Add the corresponding components of two points.

Parameters
Name Type Description

point1

CONST_OBJECT Point

Input point 1

point2

CONST_OBJECT Point

Input point 2

Return values
Name Type Description

pointOut

OBJECT Point

Output point

Sample
pointOut = Point.add(point1, point2)
addConstant()
Short description

Add a constant to each component.

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point

constant

FLOAT

The constant

Return values
Name Type Description

pointOut

OBJECT Point

Output point

Sample
pointOut = Point.addConstant(pointIn, constant)
clone()
Short description

Create a copy of a point.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

clonedPoint

OBJECT Point

Copy of the input point

Sample
clonedPoint = Point.clone(point)
create()
Short description

Create 2D or 3D point(s). The third z-coordinate input is optional, if omitted a 2D point is created, otherwise a 3D point. Vector input is allowed to create vectors of points. The input vectors must then all be of equal length. The following input combinations are allowed: Two scalar floats give a 2D point (x,y) Three scalar floats give a 3D point (x,y,z) Two vectors of equal length give a vector of 2D points Three vectors of equal length give a vector of 3D points

Parameters
Name Type Description

x

FLOAT

X coordinate, a scalar or vector.

y

FLOAT

Y coordinate, a scalar or vector.

z

FLOAT

Z coordinate, a scalar or vector. Optional: if omitted, 2D points will be created.

Return values
Name Type Description

point

OBJECT Point

The created point or vector of points.

Sample
point = Point.create({1.0, 2.0}, {3.0, 4.0})
cross()
Short description

Calculates the cross product of two point vectors (only 3D). The cross product is anti-commutative: a x b = -(b x a)

See also

Point.dot

Parameters
Name Type Description

a

CONST_OBJECT Point

Input point

b

CONST_OBJECT Point

Input point

Return values
Name Type Description

product

OBJECT Point

The cross product

Sample
product = Point.cross(a, b)
divide()
Short description

Divide the components of the first point with the corresponding components of the second point.

Parameters
Name Type Description

point1

CONST_OBJECT Point

Input point 1

point2

CONST_OBJECT Point

Input point 2

Return values
Name Type Description

pointOut

OBJECT Point

Output point

Sample
pointOut = Point.divide(point1, point2)
divideConstant()
Short description

Divide each component with a constant.

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point

constant

FLOAT

The constant

Return values
Name Type Description

pointOut

OBJECT Point

Output point

Sample
pointOut = Point.divideConstant(pointIn, constant)
dot()
Short description

Calculates the dot product of two point vectors of the same dimensionality (e.g. x1*x2+y1*y2+z1*z2).

See also

Point.cross

Parameters
Name Type Description

point1

CONST_OBJECT Point

Input point

point2

CONST_OBJECT Point

Input point

Return values
Name Type Description

product

FLOAT

The dot product

Sample
product = Point.dot(point1, point2)
getDistance()
Short description

Compute the distance between the two points of the same dimensionality (2D or 3D).

Parameters
Name Type Description

point1

CONST_OBJECT Point

Input point

point2

CONST_OBJECT Point

Input point

Return values
Name Type Description

distance

FLOAT

Distance between the points

Sample
distance = Point.getDistance(point1,point2)
getDistanceToLine()
Short description

Calculates the distance from a point to a line (2D/3D).

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point

line

CONST_AUTO

Input line (Shape/Shape3D).

Return values
Name Type Description

distance

FLOAT

The distance from point to line or nil for invalid input combination

Sample
local distance = Point.getDistanceToLine(pointIn, line)
getDistanceToPlane()
Short description

Calculates the distance from a point to a plane (only 3D).

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point

plane

CONST_OBJECT Shape3D

Input plane.

Return values
Name Type Description

distance

FLOAT

The distance from point to plane

Sample
local distance = Point.getDistanceToPlane(pointIn, plane)
getX()
Short description

Get the X coordinate of a point.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

x

FLOAT

x coordinate of the point

Sample
x = Point.getX(point)
getXY()
Short description

Get the X and Y coordinates of a point.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

x

FLOAT

x coordinate of the point

y

FLOAT

y coordinate of the point

Sample
x,y = Point.getXY(point)
getXYZ()
Short description

Get the X, Y and Z coordinates of a point (only 3D).

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

x

FLOAT

x coordinate of the point

y

FLOAT

y coordinate of the point

z

FLOAT

z coordinate of the point

Sample
x,y,z = Point.getXYZ(point)
getY()
Short description

Get the Y coordinate of a point.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

y

FLOAT

y coordinate of the point

Sample
y = Point.getY(point)
getZ()
Short description

Get the Z coordinate of a point (only 3D).

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

z

FLOAT

z coordinate of the point

Sample
z = Point.getZ(point)
is2D()
Short description

Check if a point is a 2D point.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

ret

BOOL

True if 2D point, otherwise false

Sample
ret = Point.is2D(point)
is3D()
Short description

Check if a point is a 3D point.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

ret

BOOL

True if 3D point, otherwise false

Sample
ret = Point.is3D(point)
isFinite()
Short description

Check if a point is finite, i.e. none of the values is Inf/NaN.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

ret

BOOL

True if finite point, otherwise false

Sample
ret = Point.isFinite(point)
isZero()
Short description

Returns true if all coordinates are zero.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

ret

BOOL

True if all coordinates are zero, otherwise false

Sample
ret = Point.isZero(point)
multiply()
Short description

Multiply the corresponding components of two points.

Parameters
Name Type Description

point1

CONST_OBJECT Point

Input point 1

point2

CONST_OBJECT Point

Input point 2

Return values
Name Type Description

pointOut

OBJECT Point

Output point

Sample
pointOut = Point.multiply(point1, point2)
multiplyConstant()
Short description

Multiply each component with a constant.

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point

constant

FLOAT

The constant

Return values
Name Type Description

pointOut

OBJECT Point

Output point

Sample
pointOut = Point.multiplyConstant(pointIn, constant)
negate()
Short description

Returns the negated point vector (every component changes its sign).

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point

Return values
Name Type Description

pointOut

OBJECT Point

The negated point

Sample
pointOut = Point.negate(pointIn)
norm()
Short description

Calculates different types of non-negative vector norms. If no enumeration is provided, the "L-2-Norm" will be calculated, which represents the magnitude or length of the point vector.

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point

type

ENUM NormType

Norm type enumeration

Return values
Name Type Description

norm

FLOAT

The norm

Sample
norm = Point.norm(pointIn)
normalize()
Short description

Returns the unit vector (length=1) with the same direction or nil if the input point vector has the length 0.

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point

Return values
Name Type Description

pointOut

OBJECT Point

The normalized point vector or nil

Sample
pointOut = Point.normalize(pointIn)
projectOntoPlane()
Short description

Projects one or multiple points onto a plane (only 3D).

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point(s)

plane

CONST_OBJECT Shape3D

The projection plane.

Return values
Name Type Description

pointOut

OBJECT Point

The point(s) on the plane

Sample
pointOut = Point.projectOntoPlane(pointIn, plane)
setX()
Short description

Set the X coordinate of a point.

Parameters
Name Type Description

point

OBJECT Point

Input point

x

FLOAT

X coordinate

Sample
Point.setX(point, x)
setXY()
Short description

Set the X and Y coordinates of a point.

Parameters
Name Type Description

point

OBJECT Point

Input point

x

FLOAT

X coordinate

y

FLOAT

Y coordinate

Sample
Point.setXY(point, x, y)
setXYZ()
Short description

Set the X, Y and Z coordinates of a point (only 3D).

Parameters
Name Type Description

point

OBJECT Point

Input point

x

FLOAT

X coordinate

y

FLOAT

Y coordinate

z

FLOAT

Z coordinate

Sample
Point.setXYZ(point, x, y, z)
setY()
Short description

Set the Y coordinate of a point.

Parameters
Name Type Description

point

OBJECT Point

Input point

y

FLOAT

Y coordinate

Sample
Point.setY(point, y)
setZ()
Short description

Set the Z coordinate of a point (only 3D).

Parameters
Name Type Description

point

OBJECT Point

Input point

z

FLOAT

Z coordinate

Sample
Point.setZ(point, z)
subtract()
Short description

Subtract the corresponding components of the second point from those of the first point.

Parameters
Name Type Description

point1

CONST_OBJECT Point

Input point 1

point2

CONST_OBJECT Point

Input point 2

Return values
Name Type Description

pointOut

OBJECT Point

Output point

Sample
pointOut = Point.subtract(point1, point2)
subtractConstant()
Short description

Subtract a constant from each component.

Parameters
Name Type Description

pointIn

CONST_OBJECT Point

Input point

constant

FLOAT

The constant

Return values
Name Type Description

pointOut

OBJECT Point

Output point

Sample
pointOut = Point.subtractConstant(pointIn, constant)
toMatrix()
Short description

Converts a point or a vector of points to a matrix.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point, or vector of points to convert to a matrix.

storeInColumns

BOOL

When true the points are placed in the columns of the matrix, when false in the rows of the matrix.

Return values
Name Type Description

matrix

OBJECT Matrix

Matrix created from the points.

Sample
matrix = Point.toMatrix(point, storeInColumns)
toString()
Short description

Get a string representation of the point.

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point

Return values
Name Type Description

str

STRING

String representation of the point

Sample
print("The point is: " .. Point.toString(point))
transform()
Short description

Transforms point or a vector of points. For 2D points a 2D transform must be supplied, for 3D points a 3D transform.

See also

Transform

Parameters
Name Type Description

point

CONST_OBJECT Point

Input point, or vector of points.

transform

CONST_OBJECT Transform

Transform to apply.

Return values
Name Type Description

transformedPoint

OBJECT Point

Transformed point(s).

Sample
transformedPoint = Point.transform(point, transform)

PointCloud

Short description

Iconic object for points in a 3D Cartesian coordinate system.

Functions

appendPoint()
Short description

Appends a new point to the specified point cloud.

Parameters
Name Type Description

inputCloud

OBJECT PointCloud

Point cloud to append the point to

x

FLOAT

X value in [mm]

y

FLOAT

Y value in [mm]

z

FLOAT

Z value in [mm]

intensity

FLOAT

Intensity value

Sample
PointCloud.appendPoint(inputCloud, x, y, z, intensity)
clone()
Short description

Returns a duplicated instance of the input cloud. This is a full copy and might be very slow dependent on the cloud size.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The cloud to clone

Return values
Name Type Description

clone

OBJECT PointCloud

The new cloned cloud object

Sample
local clone = PointCloud.clone(inputCloud)
create()
Short description

Creates a new empty point cloud object

Parameters
Name Type Description

colorMode

ENUM ColorMode

The color mode of this point cloud. Defaults to "INTENSITY".

Return values
Name Type Description

newCloud

OBJECT PointCloud

The newly created cloud

Sample
local newCloud = PointCloud.create()
createFromPoints()
Short description

Creates a point cloud from a vector of Point objects containing the Cartesian coordinates and an optional intensity value or vector of intensity values. If the input points are only 2D, the z-coordinate of all points in the point cloud is set to 0.

Parameters
Name Type Description

points

CONST_OBJECT Point

Vector of Point objects containing the coordinates.

intensity

FLOAT

Select an intensity between 0 and 1 for the points in the point cloud. Input can be either a single value or one value per point. Default is 1.0.

Return values
Name Type Description

pointcloud

OBJECT PointCloud

The resulting point cloud.

Sample
local pointcloud = PointCloud.createFromPoints(points, intensity)
createFromVector()
Short description

Creates a point cloud from vectors of x, y, z and intensity values.

Parameters
Name Type Description

x

FLOAT

X values in [mm]

y

FLOAT

Y values in [mm]

z

FLOAT

Z values in [mm]

intensity

FLOAT

Intensity values

Return values
Name Type Description

pointcloud

OBJECT PointCloud

The resulting point cloud.

Sample
local pointcloud = PointCloud.createFromVector(x, y, z, intensity)
extractIndices()
Short description

Extract a number of points referenced by indices from a point cloud.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The input point cloud.

indices

INT

Indices of the points which will be copied to the output cloud.

negative

BOOL

Set to true to invert the filter behavior (copy all points not in the indices vector), default is false.

Return values
Name Type Description

outputCloud

OBJECT PointCloud

The extracted point cloud or nil, if the input point cloud is empty.

Sample
local outputCloud = PointCloud.extractIndices(inputCloud, indices, negative)
getBoundingBox()
Short description

Compute the axis-aligned bounding box of all points in this cloud and return a Shape3D object.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The input point cloud.

Return values
Name Type Description

box

OBJECT Shape3D

The bounding box or nil, if the input point cloud is empty.

Sample
local box = PointCloud.getBoundingBox(inputCloud)
getBounds()
Short description

Compute the axis-aligned bounding box of all points in this cloud and return the float values.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The input point cloud

Return values
Name Type Description

minX

FLOAT

X-value of minimum point [mm]

minY

FLOAT

Y-value of minimum point [mm]

minZ

FLOAT

Z-value of minimum point [mm]

maxX

FLOAT

X-value of maximum point [mm]

maxY

FLOAT

Y-value of maximum point [mm]

maxZ

FLOAT

Z-value of maximum point [mm]

Sample
local minX, minY, minZ, maxX, maxY, maxZ = PointCloud.getBounds(inputCloud)
getCentroid()
Short description

Compute the centroid (or geometric center) as the arithmetic mean position of all points in this cloud.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The input point cloud.

Return values
Name Type Description

centroid

OBJECT Point

The centroid or nil, if the input point cloud is empty.

Sample
local centroid = PointCloud.getCentroid(inputCloud)
getColor()
Short description

Get the RGBA color values of the specified points in the point cloud. Works only if the point cloud’s color mode is "RGBA".

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The input point cloud

indices

INT

Indices of the points to get the color from

Return values
Name Type Description

red

INT

Red color component (single value or vector of same length as indices) or nil

green

INT

Green color component (single value or vector of same length as indices) or nil

blue

INT

Blue color component (single value or vector of same length as indices) or nil

alpha

INT

Alpha/opacity component (single value or vector of same length as indices) or nil

Sample
local red, green, blue, alpha = PointCloud.getColor(inputCloud, indices)
getColorMode()
Short description

Returns the color mode of the point cloud.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The input point cloud

Return values
Name Type Description

colorMode

ENUM ColorMode

The color mode of this cloud

Sample
local colorMode = PointCloud.getColorMode(inputCloud)
getIntensity()
Short description

Get the intensity value of the specified points in the point cloud. Works only if the point cloud’s color mode is "INTENSITY".

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The input point cloud

indices

INT

Indices of the points to get the intensity from

Return values
Name Type Description

intensity

FLOAT

Intensity (single value or vector of same length as indices) or nil

Sample
local intensity = PointCloud.getIntensity(inputCloud, indices)
getPoint()
Short description

Returns the x, y, z and intensity value of the specified point in the point cloud as single float values.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The point cloud to get the point from

index

INT

Point index starting from 0

Return values
Name Type Description

x

FLOAT

X value in [mm]

y

FLOAT

Y value in [mm]

z

FLOAT

Z value in [mm]

intensity

FLOAT

Intensity value

Sample
local x,y,z,intensity = PointCloud.getPoint(inputCloud, index)
getPoint3D()
Short description

Returns the 3D coordinates of the specified point in the point cloud as Point object and the intensity as float value.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The point cloud to get the point from

index

INT

Optional point index starting from 0

Return values
Name Type Description

point

OBJECT Point

The 3D coordinates as Point object.

intensity

FLOAT

Intensity value

Sample
local point, intensity = PointCloud.getPoint3D(inputCloud, index)
getPoints()
Short description

Returns the x, y, z and intensity value of all points in the point cloud as vectors of float values. This function is deprecated, please use PointCloud.toVector instead.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

Point cloud to get the points from

Return values
Name Type Description

x

FLOAT

X values in [mm]

y

FLOAT

Y values in [mm]

z

FLOAT

Z values in [mm]

intensity

FLOAT

Intensity values

Sample
local x,y,z,intensity = PointCloud.getPoints(inputCloud)
getSize()
Short description

Returns the dimensions of the point cloud.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The point cloud to get the size from

Return values
Name Type Description

size

INT

The number of points in this cloud

width

INT

The width of the cloud if organized, total size if not

height

INT

The height of the cloud if organized, 1 if not

Sample
local size,width,height = PointCloud.getSize(inputCloud)
isDense()
Short description

Returns true if all the points in this point cloud have valid coordinates (i.e. not Inf/NaN). Clouds provided by a sensor may contain invalid points. This is typically used to ignore points with low confidence and at the same time keep the organized matrix structure of the cloud.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The point cloud to get the attribute from

Return values
Name Type Description

isDense

BOOL

True if all the points in this point cloud have valid coordinates

Sample
local isDense = PointCloud.isDense(inputCloud)
isOrganized()
Short description

Returns true if the points in this point cloud are organized in rows and columns (i.e. height > 1). This is typically the case when the data has been created by a matrix sensor, e.g. in a time-of-flight camera.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The point cloud to get the attribute from

Return values
Name Type Description

isOrganized

BOOL

True if the points in this point cloud are organized in rows and columns

Sample
local isOrganized = PointCloud.isOrganized(inputCloud)
load()
Short description

Load a point cloud from the specified file path. The format is defined by the file extension: .ply: Polygon File Format ("ascii" mode only) .pcd: Point Cloud Data File Format ("ascii", "binary" or "binary_compressed" mode) .ssr: SICK Sensor Record .json: JSON .msgpack: MessagePack

See also

File, Object.load

Parameters
Name Type Description

filepath

STRING

The path and name of the file to load the point cloud from.

Return values
Name Type Description

loadedCloud

OBJECT PointCloud

The PointCloud object which is loaded.

Sample
local loadedCloud = PointCloud.load("resources/cloud.pcd")
merge()
Short description

Merge two point clouds by creating a new cloud and appending the points of both clouds to it. The color mode of both point clouds must be identical.

Parameters
Name Type Description

inputCloud1

CONST_OBJECT PointCloud

The first point cloud.

inputCloud2

CONST_OBJECT PointCloud

The second point cloud.

Return values
Name Type Description

mergedCloud

OBJECT PointCloud

The merged point cloud.

Sample
local mergedCloud = PointCloud.merge(inputCloud1, inputCloud2)
mergeInplace()
Short description

In-place version of the PointCloud.merge function that modifies the input point cloud. See base function for full documentation. The color mode of both point clouds must be identical.

See also

PointCloud.merge

Parameters
Name Type Description

inputCloud1

OBJECT PointCloud

The first point cloud. This point cloud is overwritten with the merged point cloud.

inputCloud2

CONST_OBJECT PointCloud

The second point cloud.

Return values
Name Type Description

result

OBJECT PointCloud

Reference to the result point cloud.

Sample
local result = PointCloud.mergeInplace(inputCloud1, inputCloud2)
resample()
Short description

Resample a point cloud using a 3D voxel grid. All points in one voxel are merged to their centroid by averaging their x, y, z and intensity values. It’s possible to specify a minimum number of points inside a voxel to ignore scattered points.

Detailed description

Data Reduction

PointCloud.resample creates an axis-aligned bounding box around the cloud which is subdivided into voxels (volumetric pixels) whose size can be defined with the voxelSizeX/Y/Z parameters.

  • All the points in one voxel of the grid are approximated with their centroid.

  • It’s possible to specify a minimum number of points inside a voxel to ignore scattered points.

Voxel Grid

Example: The four green points inside this voxel are replaced with their centroid (red point) in the output cloud.

PointCloud.sample chooses a number of random sample points with a uniform probability.

  • It’s a bit faster than resample and preserves the relative density of the cloud.

DataReduction1

Input cloud with 50.000 points

DataReduction2

PointCloud.sample(4000) - sample 4000 points

DataReduction3

PointCloud.resample(5, 5, 5) - 5x5x5 mm voxel

DataReduction4

PointCloud.resample(5, 5, 5, 10) - min. 10 points per voxel

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The input point cloud.

voxelSizeX

FLOAT

Voxel size in x-direction.

voxelSizeY

FLOAT

Voxel size in y-direction (uses voxelSizeX if not set).

voxelSizeZ

FLOAT

Voxel size in z-direction (uses voxelSizeX if not set).

minNumPoints

INT

Minimum number of points inside a voxel for creating a point in the output cloud, default is 1.

Return values
Name Type Description

resampledCloud

OBJECT PointCloud

The resampled point cloud.

Sample
local resampledCloud = PointCloud.resample(inputCloud, 5.0, 5.0, 5.0, 10)
save()
Short description

Save a point cloud to the specified file path. Overwrites the file if it already exists. The format is defined by the file extension: .ply: Polygon File Format ("ascii" mode only) .pcd: Point Cloud Data File Format ("ascii" or "binary" mode) .ssr: SICK Sensor Record .json: JSON (Optional useBinaryPCD parameter not supported). .msgpack: MessagePack (Optional useBinaryPCD parameter not supported).

See also

File, Object.save

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The PointCloud object which is saved.

filepath

STRING

The path and name of the file to save the point cloud to.

useBinaryPCD

BOOL

Only applies for .pcd file format. If true write coordinates in binary mode instead of ASCII. Default is false.

Return values
Name Type Description

success

BOOL

Returns true if the point cloud has been successfully saved.

Sample
local success = PointCloud.save(inputCloud, "private/cloud.pcd")
setColor()
Short description

Set the RGBA color values of the specified points in the point cloud. Works only if the point cloud’s color mode is "RGBA".

Parameters
Name Type Description

inputCloud

OBJECT PointCloud

The input point cloud

indices

INT

Indices of the points to set the color for

red

INT

Red color component in range [0-255]. Must be either a single value or vector of same length as indices.

green

INT

Green color component in range [0-255]. Must be either a single value or vector of same length as indices.

blue

INT

Blue color component in range [0-255]. Must be either a single value or vector of same length as indices.

alpha

INT

Alpha/opacity component in range [0-255] (optional). Must be either a single value or vector of same length as indices or empty. Defaults to 255.

Return values
Name Type Description

success

BOOL

Returns true on success.

Sample
PointCloud.setColor(inputCloud, indices, red, green, blue)
setIntensity()
Short description

Set the intensity value of the specified points in the point cloud. Works only if the point cloud’s color mode is "INTENSITY".

Parameters
Name Type Description

inputCloud

OBJECT PointCloud

The input point cloud

indices

INT

Indices of the points to set the intensity for

intensity

FLOAT

Intensity value to set. Must be either a single value or vector of same length as indices.

Return values
Name Type Description

success

BOOL

Returns true on success.

Sample
PointCloud.setIntensity(inputCloud, indices, intensity)
setPoint()
Short description

Sets the x, y, z and intensity value of the specified point in the point cloud.

Parameters
Name Type Description

inputCloud

OBJECT PointCloud

Point cloud to set the point to

index

INT

Point index starting from 0

x

FLOAT

X value in [mm]

y

FLOAT

Y value in [mm]

z

FLOAT

Z value in [mm]

intensity

FLOAT

Intensity value, optional

Sample
PointCloud.setPoint(inputCloud, index, x, y, z, intensity)
toImage()
Short description

Create a range image from a pointcloud. The image is formed by projection of the point in the pointcloud onto the z-zero plane with normal (0, 0, 1). The x and y axes of the pointcloud are aligned with the x and y axes of the resulting image. The employed method is sometimes referred to as splatting, i.e., each point in the pointcloud is splatted onto the plane, writing its z-distance to a splat area given in pixels. Pixels which are not hit by any splats are marked as missing data. If such holes appear in the generated image try increasing the splat sizes, make the pixel sizes larger or use methods to fill missing data. The function can return two images, one with the z-distance in each pixel and one with the intensity value from the pointcloud. The output image is of type UINT16 and the size of the image is calculated based on the input parameters. Image world coordinate system handling: The world coordinate settings, e.g., origin in x,y,z and pixel sizes are set based on the input parameters to the function. Missing data handling: Pixels in the output range image and intensity image will be zero (missing data) if no point in the pointcloud had effect over that pixel. Missing data can be reduced by increasing the splat size or by post processing.

Keywords

convert, heightmap, project, splat

Parameters
Name Type Description

pointcloud

CONST_OBJECT PointCloud

The input pointcloud.

box

CONST_OBJECT Shape3D

An axis-aligned box. All pointcloud points within this box are used for creating the image. Can for example be the bounding box of the pointcloud to include all points. The coordinate system origin of the resulting image is defined by the box.

pixelSizes

FLOAT

Vector defining the pixel sizes of the output image {x, y, z}. At least one value must be set and will then affect the x and y resolution. The z-resolution will be automatically estimated if unset.

splatSizes

INT

Optional vector of splat kernel sizes in the x and y dimensions. To select a splat size of 5 use {5}, for anisotropic splatting use for example {3, 5}. Default is {3}.

mode

ENUM PointCloud.toImageMode

If several points in the pointcloud splat onto the same pixel, it must be choosen if the TOPMOST or BOTTOMMOST value is written to the result pixel. Default is TOPMOST.

generateIntensity

BOOL

Select if an intensity image is to be generated also from the intensity part of the pointcloud. Defaults to true.

Return values
Name Type Description

rangeImage

OBJECT Image

Output range image of UINT16 type.

intensityImage

OBJECT Image

Intensity image of UINT8 type, if generated.

Sample
rangeImageReference, intensityImage = PointCloud.toImage(pointcloud, boundingBox, {0.2})
toImageInplace()
Short description

Create a range image from a pointcloud. The image is formed by projection of the point in the point cloud onto the plane with normal (0, 0, 1). The x and y axes of the point cloud are aligned with the x and y axes of the resulting image. The employed method is sometimes referred to as splatting, i.e., each point in the pointcloud is splatted onto the plane, writing its z-distance to an splat area given in pixels. Pixels which are not hit by any splats are marked as missing data. If such holes appear in the generated image try increasing the splat sizes, make the pixel sizes larger or use methods to fill missing data. The operation is performed inplace for the input image, that is, the content of image will change inside the function. The function returns two images, one with the z-distance in each pixel and one with the intensity value from the pointcloud. Supported rangeImageReference types are unsigned integer images, i.e., UINT8, UINT16, UINT32 and UINT64. Image world coordinate system handling: The input image defines the world coordinate system and this image is updated and returned inplace. Make sure to set pixel sizes and origin to appropriate values before calling this function to achieve the desired result. Missing data handling: Pixels in the output range image and intensity image will be zero (missing data) if no point in the pointcloud had effect over that pixel. Missing data can be reduced by increasing the splat sizes or by post processing.

Keywords

convert, heightmap, project, splat

Parameters
Name Type Description

pointcloud

CONST_OBJECT PointCloud

The input pointcloud

rangeImageReference

OBJECT Image

Both input and output image into which to render the result. Make sure to set pixel sizes and origin of this image to appropriate values before calling this function to achieve the desired result.

splatSizes

INT

Optional vector of splat kernel sizes in the x and y dimensions. To select a splat size of 5 use {5}, for anisotropic splatting use for example {3, 5}. Default is {3}.

mode

ENUM PointCloud.toImageMode

If several points in the pointcloud splat onto the same pixel, it must be choosen if the TOPMOST or BOTTOMMOST value is written to the result pixel. Default is true.

includeIntensity

BOOL

Select if an intensity image should also be generated. Defaults to true.

Return values
Name Type Description

rangeImageReference

OBJECT Image

Reference to the output range image.

intensityImage

OBJECT Image

The resulting intensity image, if generated.

Sample
rangeImageReference, intensityImage = PointCloud.toImageInplace(pointcloud, rangeImageReference, {3}, "TOPMOST", true)
toPoints()
Short description

Returns the 3D coordinates of all points in the point cloud as vector of Point objects and the intensities as vector of float values.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

Point cloud to get the points from

Return values
Name Type Description

points

OBJECT Point

3D coordinates as vector of Point objects.

intensities

FLOAT

Intensities as vector of float values

Sample
local points, intensities = PointCloud.toPoints(inputCloud)
toString()
Short description

Gets a user-friendly string description of the point cloud, containing important properties.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The point cloud to describe.

Return values
Name Type Description

str

STRING

User-friendly description of the point cloud.

Sample
str = PointCloud.toString(inputCloud)
toVector()
Short description

Returns the x, y, z and intensity value of all points in the point cloud as vectors of float values.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

Point cloud to get the points from

Return values
Name Type Description

x

FLOAT

X values in [mm]

y

FLOAT

Y values in [mm]

z

FLOAT

Z values in [mm]

intensity

FLOAT

Intensity values

Sample
local x,y,z,intensity = PointCloud.toVector(inputCloud)
transform()
Short description

Transform a point cloud. Fails if the transform is not a 3D transform.

Parameters
Name Type Description

inputCloud

CONST_OBJECT PointCloud

The input point cloud.

transform

CONST_OBJECT Transform

Transform to apply.

Return values
Name Type Description

transformedCloud

OBJECT PointCloud

Transformed point cloud or nil on error

Sample
local transformedCloud = PointCloud.transform(inputCloud, transform)
transformInplace()
Short description

In-place version of the PointCloud.transform function that modifies the input point cloud. See base function for full documentation.

Parameters
Name Type Description

inputCloud

OBJECT PointCloud

The input point cloud. This point cloud is overwritten with the transformed point cloud.

transform

CONST_OBJECT Transform

Transform to apply.

Return values
Name Type Description

result

OBJECT PointCloud

Reference to the result point cloud or nil on error.

Sample
local result = PointCloud.transformInplace(inputCloud, transform)

PointCloud.Matching

Short description

Point cloud matching algorithms

Overview

PointCloud.Matching.Halcon

Short description

Point cloud matching algorithms based on Halcon

Overview

PointCloud.Matching.Halcon.SurfaceMatcher

Short description

Implements surface-based matching from Halcon. See operator create_surface_model for additional information. The surface model is created by resampling a teach object with a certain distance. The teach object can be either a PointCloud with additional normal information provided by a n by 4 Matrix or a Mesh. The sampling distance must be specified in the parameter relativeSamplingDistance and is parametrized relative to the diameter of the axis-parallel bounding box of the teach object. For example, if relativeSamplingDistance is set to 0.05 and the diameter of model is 100 mm, the points sampled from the object’s surface will be approximately 5 mm apart. The sampled points are used for the approximate matching in the match() call. Note that outlier points in the teach model should be avoided, as they would corrupt the diameter. Reducing relativeSamplingDistance leads to more points, and in turn to a more stable but slower matching. Increasing relativeSamplingDistance leads to fewer points, and in turn to a less stable but faster matching. The sampled points are used for finding the object model in a scene during a match() call. For this, all possible pairs of points from the point set are examined, and the distance and relative surface orientation of each pair is computed. Both values are discretized and stored for matching. The teach model is resampled a second time for the pose refinement. The second sampling is done with a smaller sampling distance, leading to more points. The parameter relativePoseRefinementSamplingDistance sets the sampling distance relative to the object’s diameter. Decreasing the value results in a more accurate pose refinement but a larger model and a slower model generation and matching. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. See Halcon’s operator find_surface_model for additional information. A minimum usage example is: local matcher = PointCloud.Matching.Halcon.SurfaceMatcher.create() local teachObject = matcher:teachMesh(teachMesh, 0.02) local scores, poses = PointCloud.Matching.Halcon.SurfaceMatcher.match(matcher, pointCloud) for index, score in ipairs(scores) do print(score, poses[index]:toString()) — transform the resampled teach model into the scene local teachObjectTransformed = teachObject:transform(poses[index]) end

Detailed description

The surface model is created by resampling a teach object with a certain distance. The teach object can be either a PointCloud with additional normal information provided by a n by 4 Matrix or a Mesh. The sampling distance must be specified in the parameter relativeSamplingDistance and is parametrized relative to the diameter of the axis-parallel bounding box of the teach object. For example, if relativeSamplingDistance is set to 0.05 and the diameter of model is 100 mm, the points sampled from the object’s surface will be approximately 5 mm apart. The sampled points are used for the approximate matching in the match() call. Note that outlier points in the teach model should be avoided, as they would corrupt the diameter. Reducing relativeSamplingDistance leads to more points, and in turn to a more stable but slower matching. Increasing relativeSamplingDistance leads to fewer points, and in turn to a less stable but faster matching.

The sampled points are used for finding the object model in a scene during a match() call. For this, all possible pairs of points from the point set are examined, and the distance and relative surface orientation of each pair is computed. Both values are discretized and stored for matching.

The teach model is resampled a second time for the pose refinement. The second sampling is done with a smaller sampling distance, leading to more points. The parameter relativePoseRefinementSamplingDistance sets the sampling distance relative to the object’s diameter. Decreasing the value results in a more accurate pose refinement but a larger model and a slower model generation and matching. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. See Halcons operator find_surface_model for additional information.

A minimum usage example is:

local matcher = PointCloud.Matching.Halcon.SurfaceMatcher.create()
local teachObject = matcher:teachMesh(teachMesh, 0.02)
local scores, poses = PointCloud.Matching.Halcon.SurfaceMatcher.match(matcher, pointCloud)
for index, score in ipairs(scores) do
  print(score, poses[index]:toString())
  -- transform the resampled teach model into the scene
  local teachObjectTransformed = teachObject:transform(poses[index])
end

Functions

create()
Short description

Create a handle for the surface-based matching.

Return values
Name Type Description

matcher

HANDLE

Handle for matcher.

Sample
local matcher = PointCloud.Matching.Halcon.SurfaceMatcher.create()
getKeypointFraction()
Short description

Get the fraction of sampled scene points used as key points.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

Return values
Name Type Description

keypointFraction

FLOAT

fraction of sampled scene points used as key points.

Sample
local keypointFraction = PointCloud.Matching.Halcon.SurfaceMatcher.getKeypointFraction(matcher)
getMaxMatches()
Short description

Gets the maximum number of matches that are returned.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

Return values
Name Type Description

maxMatches

INT

The maximum number of matches.

Sample
local maxMatches = PointCloud.Matching.Halcon.SurfaceMatcher.getMaxMatches(matcher)
getMinScore()
Short description

Get the minimum score. The score is the relative number of sampled model points found in the matching. A model point is defined to be found if there is a scene point close to it.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

Return values
Name Type Description

minimumScore

FLOAT

Minimum score of the found matchings.

Sample
local minimumScore = PointCloud.Matching.Halcon.SurfaceMatcher.getMinScore(matcher)
getMinSeparation()
Short description

Get the minimum relative overlap distance between matches.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

Return values
Name Type Description

overlapDistance

FLOAT

Minimum relative overlap distance between matches.

Sample
local overlapDistance = PointCloud.Matching.Halcon.SurfaceMatcher.getMinSeparation(matcher)
getNormalComputationMethod()
Short description

Get the normal computation method

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

Return values
Name Type Description

type

ENUM NormalComputationMethod

Normal computation method

Sample
local type = PointCloud.Matching.Halcon.SurfaceMatcher.getNormalComputationMethod(matcher)
getPoseRefinementParameters()
Short description

Get parameters related to the dense pose refinement.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

Return values
Name Type Description

relativeDistanceThreshold

FLOAT

Distance threshold for dense pose refinement relative to the diameter of the surface model.

relativeScoringThreshold

FLOAT

Distance threshold for scoring relative to the diameter of the surface model.

Sample
local relativeDistanceThreshold, relativeScoringThreshold = PointCloud.Matching.Halcon.SurfaceMatcher.getPoseRefinementParameters(matcher)
getRelativeSamplingDistance()
Short description

Get the relative sampling distance for the point cloud input during matching.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

Return values
Name Type Description

relativeSamplingDistance

FLOAT

Sampling distance relative to the diameter of point cloud input during matching.

Sample
local relativeSamplingDistance = PointCloud.Matching.Halcon.SurfaceMatcher.getRelativeSamplingDistance(matcher)
match()
Short description

Perform the matching of the teach object in the point cloud: The matching is divided into three steps: 1.) Approximate matching: The approximate poses of the instances of the surface model in the scene are searched. 2.) Sparse pose refinement: In this second step, the approximate poses found in the previous step are further refined. This increases the accuracy of the poses and the significance of the score value. The sparse pose refinement uses the sampled scene points from the approximate matching. The pose is optimized such that the distances from the sampled scene points to the plane of the closest model point are minimal. The plane of each model point is defined as the plane perpendicular to its normal. 3.) Dense pose refinement: Accurately refines the poses found in the previous steps. This step works similar to the sparse pose refinement and minimizes the distances between the scene points and the planes of the closest model points.

Detailed description

The matching is divided into three steps:

  1. Approximate matching: The approximate poses of the instances of the surface model in the scene are searched.

  2. Sparse pose refinement: In this second step, the approximate poses found in the previous step are further refined. This increases the accuracy of the poses and the significance of the score value. The sparse pose refinement uses the sampled scene points from the approximate matching. The pose is optimized such that the distances from the sampled scene points to the plane of the closest model point are minimal. The plane of each model point is defined as the plane perpendicular to its normal.

  3. Dense pose refinement: Accurately refines the poses found in the previous steps. This step works similar to the sparse pose refinement and minimizes the distances between the scene points and the planes of the closest model points.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

pointCloud

CONST_OBJECT PointCloud

The point cloud for matching.

Return values
Name Type Description

score

FLOAT

The score is between 0 and 1. Relative number of sampled model points found in the matching. A model point is defined to be found if there is a scene point close to it.

pose

OBJECT Transform

The pose for the teach object in the matching result.

Sample
local score, pose = PointCloud.Matching.Halcon.SurfaceMatcher.match(matcher, pointCloud)
setKeypointFraction()
Short description

Set the fraction of sampled scene points used as key points. A set of key points is selected from the sampled scene points. The number of selected key points is controlled with the parameter keypointFraction. Increasing keypointFraction means that more key points are selected from the scene, resulting in a slower but more stable matching.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

keypointFraction

FLOAT

Fraction of sampled scene points used as key points. Must be between 0 and 1. Default is 0.2.

Return values
Name Type Description

success

BOOL

True on success, false if parameters where invalid.

Sample
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setKeypointFraction(matcher, keypointFraction)
setMaxMatches()
Short description

Sets the maximum number of matches that are returned.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

maxMatches

INT

The maximum number of matches. Must be larger than 0. Default is 1.

Return values
Name Type Description

success

BOOL

True on success, false if parameters where invalid.

Sample
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setMaxMatches(matcher, maxMatches)
setMinScore()
Short description

Set the minimum score. The score is the relative number of sampled model points found in the matching. A model point is defined to be found if there is a scene point close to it.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

minimumScore

FLOAT

Minimum score of the found matchings. Must be positive. Default is 0.

Return values
Name Type Description

success

BOOL

True on success, false if parameters where invalid.

Sample
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setMinScore(matcher, minimumScore)
setMinSeparation()
Short description

Set the minimum relative overlap distance between matches. The distance is computed as the diference between the matches axis-aligned bounding boxes.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

overlapDistance

FLOAT

Minimum relative overlap distance between matches. Must be non-negative. Default is 0.5.

Return values
Name Type Description

success

BOOL

True on success, false if parameters where invalid.

Sample
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setMinSeparation(matcher, overlapDistance)
setNormalComputationMethod()
Short description

Set the normal computation method

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

type

ENUM NormalComputationMethod

Normal computation method. Default is 'FAST'.

Return values
Name Type Description

success

BOOL

True on success, false if parameters where invalid.

Sample
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setNormalComputationMethod(matcher, type)
setPoseRefinementParameters()
Short description

Set parameters related to the dense pose refinement.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

relativeDistanceThreshold

FLOAT

Distance threshold for dense pose refinement relative to the diameter of the surface model. Only scene points that are closer to the object than this distance are used for the optimization. Must be larger than zero. Default is 0.005.

relativeScoringThreshold

FLOAT

Distance threshold for scoring relative to the diameter of the surface model. Only scene points that are closer to the object than this distance are considered to be 'on the model' when computing the score after the pose refinement. Must be larger than zero. Default is 0.05.

Return values
Name Type Description

success

BOOL

True on success, false if parameters where invalid.

Sample
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setPoseRefinementParameters(matcher, relativeDistanceThreshold, relativeScoringThreshold)
setRelativeSamplingDistance()
Short description

Set the relative sampling distance for the point cloud input during matching.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

relativeSamplingDistance

FLOAT

Sampling distance relative to the diameter of point cloud input during matching. Must be between 0 and 1. Default is 0.05.

Return values
Name Type Description

success

BOOL

True on success, false if parameters where invalid.

Sample
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setRelativeSamplingDistance(matcher, relativeSamplingDistance)
teachMesh()
Short description

Teach a model for matching from a mesh object.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

mesh

CONST_OBJECT Mesh

Mesh representing the teach object.

relativeSamplingDistance

FLOAT

Sampling distance relative to axis-parallel bounding box used for sampling the teach model.

relativePoseRefinementSamplingDistance

FLOAT

Set the sampling distance for the pose refinement relative to the teach object’s diameter. Decreasing this value leads to a more accurate pose refinement but a larger model and slower model generation and refinement. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. Default is 0.01.

Return values
Name Type Description

sampledTeachObject

OBJECT PointCloud

The resampled point cloud that is used for the approximate matching in the match() call.

Sample
local teachObject = PointCloud.Matching.Halcon.SurfaceMatcher.teachMesh(matcher, mesh, relativeSamplingDistance, relativePoseRefinementSamplingDistance)
teachPointCloud()
Short description

Teach a model for matching from a point cloud and normal information.

Parameters
Name Type Description

matcher

HANDLE

Handle for matcher.

pointCloud

CONST_OBJECT PointCloud

Point cloud with n points representing the teach object.

normals

CONST_OBJECT Matrix

The normals represented as n x 4 matrix.

relativeSamplingDistance

FLOAT

Sampling distance relative to axis-parallel bounding box used for sampling the teach model.

relativePoseRefinementSamplingDistance

FLOAT

Set the sampling distance for the pose refinement relative to the teach object’s diameter. Decreasing this value leads to a more accurate pose refinement but a larger model and slower model generation and refinement. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. Default is 0.01.

Return values
Name Type Description

sampledTeachObject

OBJECT PointCloud

The resampled point cloud that is used for the approximate matching in the match() call.

Sample
local teachObject = PointCloud.Matching.Halcon.SurfaceMatcher.teachPointCloud(matcher, pointCloud, normals, relativeSamplingDistance, relativePoseRefinementSamplingDistance)

PointCloud.RangeFilter

Short description

Removes points outside of the defined attribute range (or inside, if the behavior is inverted with setNegative(true)). By default, the filter does not remove any points.

Functions

create()
Short description

Create a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
local handle = PointCloud.RangeFilter.create()
filter()
Short description

Return the area filtered PointCloud.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

inputCloud

CONST_OBJECT PointCloud

The PointCloud object which is filtered

Return values
Name Type Description

filteredCloud

OBJECT PointCloud

The area filtered PointCloud

Sample
local areaCloud = PointCloud.RangeFilter.filter(handle, cloud)
setIntensityRange()
Short description

Set the filter range for intensity values. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

minIntensity

FLOAT

Minimum intensity value in range [0.0-1.0]

maxIntensity

FLOAT

Maximum intensity value in range [0.0-1.0]

Sample
PointCloud.RangeFilter.setIntensityRange(handle, 0.8, 1.0)
setNegative()
Short description

Set to true to invert the filter behavior (return points outside of range).

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

behavior

BOOL

Invert filter behavior, default is false

Sample
PointCloud.RangeFilter.setNegative(handle, true)
setXRange()
Short description

Set the filter range in x-direction. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

minX

FLOAT

Minimum x value

maxX

FLOAT

Maximum x value

Sample
PointCloud.RangeFilter.setXRange(handle, -10.5, 15.0)
setYRange()
Short description

Set the filter range in y-direction. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

minY

FLOAT

Minimum y value

maxY

FLOAT

Maximum y value

Sample
PointCloud.RangeFilter.setYRange(handle, -10.5, 15.0)
setZRange()
Short description

Set the filter range in z-direction. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

minZ

FLOAT

Minimum z value

maxZ

FLOAT

Maximum z value

Sample
PointCloud.RangeFilter.setZRange(handle, -10.5, 15.0)

Profile

Short description

A data type for vector of 1D measurements. Three main components of the data type are - A vector of measurement values represented in 32 bit float precision. - An optional vector of valid flags indicating if the measurement value at the same index is valid. An integer representation is used where 0 means invalid and 1 means valid measurement. A global flag indicates if algorithms must consider the valid flags vector at all in computations. - Coordinate information for each measurement value, relating the measurement to a world position (temporal or spatial). The main purpose of the Profile type is for 1D processing, e.g., filtering finding peaks and edges, analyze trends, matching 1D patterns etc. Processing is done on the measurement vector, taking the valid flag vector into account if enabled. The purpose of the coordinate vector is to relate the measurements with a world position. The world position can be both temporal or spatial, e.g., time, angle or 2D (x,y) position. The following three examples illustrate possible use cases for the Profile type: Example 1: The measurement values represent the number of sent packages in a logistics center each day. The coordinate information represents time (day) and the valid flags vector if there was a valid package count on the corresponding day. Example 2: The measurements are range values from a LiDAR scan in polar format. The coordinate is the angle for each range measurement. The valid flag vector indicates whether the corresponding range value is valid, e.g., if there was a reliable "echo" received. Example 3: The measurement values are the height values sampled evenly along a straight line in a heightmap image. The coordinate vector in this case is a (x,y) world coordinate in millimeters or pixels, where each height value was sampled. As heightmaps can contain missing data pixels (no height value available), the valid flag vector carries this information. The coordinate information can be represented in different ways: An implicit representation stores a start coordinate (1D float value or 2D point) and a constant delta (1D float value or 2D vector). An explicit representation stores the coordinate (1D float value or 2D point) in a vector of the same length as the measurement vector. How the coordinate information is represented is determined when the Profile object is created. There is also a 'isClosed'-flag indicating if the coordinates wraps around so that the first and last samples are neighbors. This can happen for example for a 360 degree LiDAR scan or if one samples height values from a circle in a heightmap. This has effect in certain filtering operations where neighboring samples are considered to produce an output.

Keywords

1d, array, scan, vector

Functions

abs()
Short description

Computes the absolute value of each measurement in the profile. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

absolute

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

Return values
Name Type Description

result

OBJECT Profile

The resulting profile.

Sample
local result = Profile.abs(profile)
absInplace()
Short description

In-place version of the Profile.abs function that modifies the input profile. See base function for full documentation.

Keywords

absolute

See also

Profile.abs

Parameters
Name Type Description

profile

OBJECT Profile

The source profile. This profile is overwritten with the result of the abs.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.absInplace(profile)
add()
Short description

Adds two profiles sample-wise. The two profiles must have the same number of measurements. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.

Keywords

plus

Parameters
Name Type Description

profile1

CONST_OBJECT Profile

The first source profile.

profile2

CONST_OBJECT Profile

The second source profile.

Return values
Name Type Description

result

OBJECT Profile

The resulting profile.

Sample
local result = Profile.add(profile1, profile2)
addConstant()
Short description

Adds a constant to the measurements of the profile. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

translate, shift

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

constant

FLOAT

The constant to add.

Return values
Name Type Description

result

OBJECT Profile

The resulting profile.

Sample
local result = Profile.addConstant(profile, constant)
addConstantInplace()
Short description

In-place version of the Profile.addConstant function that modifies the input profile. See base function for full documentation.

Keywords

translate, shift

Parameters
Name Type Description

profile

OBJECT Profile

The source profile. This profile is overwritten with the result of the sum.

constant

FLOAT

The constant to add.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.addConstantInplace(profile, constant)
addInplace()
Short description

In-place version of the Profile.add function that modifies the input profile. See base function for full documentation.

Keywords

plus

Parameters
Name Type Description

profile1

OBJECT Profile

The first source profile. This profile is overwritten with the result of the sum.

profile2

CONST_OBJECT Profile

The second source profile.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.addInplace(profile1, profile2)
addNoise()
Short description

Adds noise to profile values. Noise with normal or uniform distribution can be selected. noiseType NORMAL: param1: standard deviation. param2: mean. noiseType UNIFORM: param1: Minimum value. param2: Maximum value.

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

noiseType

ENUM NoiseType

Distribution of noise. NORMAL or UNIFORM.

param1

FLOAT

Standard deviation if noiseType NORMAL (Default value 1.0). Min value if noiseType UNIFORM (Default value -1.0).

param2

FLOAT

Mean value if noiseType NORMAL (Default value 0.0). Max value if noiseType UNIFORM (Default value 1.0).

randSeed

INT

Random seed, optional. No new seed is set if negative. Default: 0

Return values
Name Type Description

result

OBJECT Profile

Profile with noise added.

Sample
local result = Profile.addNoise(profile, noiseType, param1, param2, randSeed)
addNoiseInplace()
Short description

In-place version of addNoise. See base function for full documentation.

Parameters
Name Type Description

profile

OBJECT Profile

The profile to add noise to.

noiseType

ENUM NoiseType

Distribution of noise. NORMAL or UNIFORM.

param1

FLOAT

Standard deviation if noiseType NORMAL (Default value 1.0). Min value if noiseType UNIFORM (Default value -1.0).

param2

FLOAT

Mean value if noiseType NORMAL (Default value 0.0). Max value if noiseType UNIFORM (Default value 1.0).

randSeed

INT

Random seed, optional. No new seed is set if negative. Default: 0

Return values
Name Type Description

result

OBJECT Profile

Reference to the profile with noise added.

Sample
local result = Profile.addNoiseInplace(profile, noiseType, param1, param2, randSeed)
aggregate()
Short description

Aggregate a set of profiles into one profile. Different aggregation operations are available such as sum, mean, min, max and median. All profiles must have the same number of measurements. All or none of the profiles must use the valid data flags. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Invalid values are excluded from the aggregation, e.g. the mean value is the mean of the valid values at a given position in the profiles. If no profile has a valid value at a particular index, the output profile will have an invalid value at that index. A profile containing the number of valid samples used in the aggregation at each index is returned. If no profile has invalid values, the valid samples profile will be constant and equal to the number of input profiles.

Keywords

max, mean, median, min, sum

Parameters
Name Type Description

profiles

CONST_OBJECT Profile

The source profiles.

operation

ENUM AggregateOperation

The type of operation used to generate the aggregate.

Return values
Name Type Description

aggregateProfile

OBJECT Profile

The aggregated profile.

validValuesProfile

OBJECT Profile

The number of entries used for each aggregated sample.

Sample
local aggregateProfile, validValuesProfile = Profile.aggregate(profiles, operation)
binarize()
Short description

Applies a threshold interval (lowerThreshold, upperThreshold) to the profile to create a binary profile. Measurement values outside the interval have the value 0 in the output profile, and values within the interval have a user-specified value. Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: If a measurement is invalid in the input profile it is invalid in the output profile.

Keywords

threshold

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

lowerThreshold

FLOAT

Lower threshold for the binarization.

upperThreshold

FLOAT

Upper threshold for the binarization.

outputValue

FLOAT

Value assigned to the measurements within the threshold interval. Optional, default value is 1.

Return values
Name Type Description

binarizedProfile

OBJECT Profile

Binarized profile.

Sample
local binarizedProfile = Profile.binarize(profile, lowerThreshold, upperThreshold, outputValue)
binarizeInplace()
Short description

In-place version of the Profile.binarize function that modifies the input profile. See base function for full documentation.

Keywords

threshold

See also

Profile.binarize

Parameters
Name Type Description

profile

OBJECT Profile

The source profile. This profile is overwritten with the binarized result.

lowerThreshold

FLOAT

Lower threshold for the binarization.

upperThreshold

FLOAT

Upper threshold for the binarization.

outputValue

FLOAT

Value assigned to the measurements within the threshold interval. Optional, default value is 1.

Return values
Name Type Description

binarizedProfile

OBJECT Profile

Reference to the result profile.

Sample
local binarizedProfile = Profile.binarizeInplace(profile, lowerThreshold, upperThreshold, outputValue)
blur()
Short description

Smooths a profile using a constant normalized box filter kernel of the given size. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Only the valid measurements are considered in the calculation. By default, all invalid measurements will be marked as invalid also in the output. If the fill flag is set to true, invalid measurements will be filled with filtered neighbor values where possible.

Keywords

box, filter, gauss, low pass, lp, smooth

Parameters
Name Type Description

profile

CONST_OBJECT Profile

Input profile.

kernelSize

INT

Size of the kernel, must be positive, odd and smaller than the profile length.

fillInvalid

BOOL

Optional flag to also fill in invalid values while filtering. Default is false.

Return values
Name Type Description

smoothProfile

OBJECT Profile

Output profile, smoothed by the blur filter.

Sample
local smoothProfile = Profile.blur(profile, kernelSize)
centralDifference()
Short description

Differentiate a profile using a first- or second-order central finite difference filter kernel. A step parameter determines how far from the center the difference is taken: First order difference: Step 1: [1 0 -1] Step 2: [1 0 0 0 -1] and so on. Second order difference: Step 1: [1 -2 1] Step 2: [1 0 -2 0 1] and so on. The output is set to zero in the beginning and end of the output profile, where the entire filter does not fit within the profile. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: If the valid data flags are enabled, the output is set as invalid if any non-zero filter coefficient hits an invalid input value or is out of bounds. For example, if differenceStep=1, the first and last output values is always set as invalid, since the 1 and -1 filter coefficients are out of bounds of the input profile.

Keywords

first, gradient, second, slope, derivative

Parameters
Name Type Description

profile

CONST_OBJECT Profile

Input profile.

differenceStep

INT

How far from the center the kernel weights are placed, must be strictly positive.

order

ENUM DifferentiationOrder

FIRST gives first order derivative and SECOND gives second order derivative.

Return values
Name Type Description

diffProfile

OBJECT Profile

Output profile created by the central difference filter.

Sample
local diffProfile = Profile.centralDifference(profile, differenceStep, order)
clamp()
Short description

Clamps each measurement value to an interval (minValue, maxValue). Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

threshold, limit

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

minValue

FLOAT

The minimum value to clamp to.

maxValue

FLOAT

The maximum value to clamp to.

Return values
Name Type Description

result

OBJECT Profile

The clamped profile.

Sample
local result = Profile.clamp(profile, minValue, maxValue)
clampInplace()
Short description

In-place version of the Profile.clamp function that modifies the input profile. See base function for full documentation.

Keywords

threshold, limit

Parameters
Name Type Description

profile

OBJECT Profile

The source profile. This profile is overwritten with the clapped result.

minValue

FLOAT

The minimum value to clamp to.

maxValue

FLOAT

The maximum value to clamp to.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.clampInplace(profile, minValue, maxValue)
clone()
Short description

Creates an independent copy of a profile.

Keywords

copy

Parameters
Name Type Description

profile

CONST_OBJECT Profile

Input profile.

Return values
Name Type Description

clonedProfile

OBJECT Profile

Copy of the input profile.

Sample
local clonedProfile = Profile.clone(profile)
concatenate()
Short description

Concatenates two profiles. The profiles must have the same coordinate type. Periodic flag and implicit coordinates are copied from the first profile. If any of the two profiles uses valid flags the result also does so.

Keywords

merge, join

Parameters
Name Type Description

profile1

CONST_OBJECT Profile

The source profile 1.

profile2

CONST_OBJECT Profile

The source profile 2.

Return values
Name Type Description

result

OBJECT Profile

Concatenated profile.

Sample
local result = Profile.concatenate(profile1, profile2)
concatenateInplace()
Short description

In-place version of concatenate that modifies the first input profile. See base function for full documentation.

Keywords

merge, join

Parameters
Name Type Description

profile1

OBJECT Profile

The source profile 1 and result profile.

profile2

CONST_OBJECT Profile

The source profile 2.

Return values
Name Type Description

result

OBJECT Profile

Reference to the concatenated profile.

Sample
local result = Profile.concatenateInplace(profile1, profile2)
convertCoordinateType()
Short description

Converts sample coordinates in the profile. Possible coordinate types: IMPLICIT_1D, EXPLICIT_1D, IMPLICIT_2D, EXPLICIT_2D. Note that the values in the profile are kept unchanged. Implicit to explicit: Change the coordinate representation from start + delta representation, to vector with absolute positions. Explicit to implicit: Change the coordinate representation from vector with absolute coordinates, to a start + delta representation. Preserving the coordinates for the first and last sample. 1D to 2D: The 1D coordinates are placed on the x-axis in the 2D coordinates. 2D to 1D: The accumulated curve length in 2D is used as the new 1D coordinates. Thus, start position is 0.0.

Parameters
Name Type Description

profile

OBJECT Profile

The profile object.

coordinateType

ENUM CoordinateType

New coordinate type.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
 local result = Profile.convertCoordinateType(profile, coordinateType)
convolve()
Short description

Convolves a profile with a given filter kernel. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Invalid flags are not allowed in this operation.

Keywords

filter

Parameters
Name Type Description

profile

CONST_OBJECT Profile

Input profile.

kernel

FLOAT

Filter kernel. Must be shorter than the profile.

Return values
Name Type Description

filteredProfile

OBJECT Profile

Output profile, filtered with the kernel.

Sample
local filteredProfile = Profile.convolve(profile, kernel)
create()
Short description

Creates a new Profile object with all measurements set to a constant value. Coordinate system handling: The coordinate representation will be implicit 1D, starting at 0 with a delta value of 1. Valid flags handling: All measurements are considered as valid. No valid flags vector is created.

See also

Profile.clone

Parameters
Name Type Description

size

INT

The number of measurements in the profile.

constantValue

FLOAT

The fill value, default is 0.

Return values
Name Type Description

profile

OBJECT Profile

The new profile.

Sample
local profile = Profile.create(size, constantValue)
createFromPoints()
Short description

Creates a new profile from a vector of points. Coordinate system handling: For 2D points the profile will have EXPLICIT_1D coordinates, where the x-coordinates will become the coordinates in the Profile and the y-coordinates will become the corresponding values. For 3D points the profile will have EXPLICIT_2D coordinates, where the x,y-coordinates will become the coordinates in the Profile and the z-coordinates will become the corresponding values.

Keywords

convert

Parameters
Name Type Description

points

CONST_OBJECT Point

The vector of points.

Return values
Name Type Description

profile

OBJECT Profile

The new profile.

Sample
local profile = Profile.createFromPoints(points)
createFromVector()
Short description

Creates a new profile from a vector of measurement values, coordinates and valid flags. Coordinate system handling: The coordinate vector is optional, if not supplied 1D implicit coordinates starting at 0 with delta 1 is created. If supplied it can be both a float vector or a vector of 2D Points. An explicit coordinate representation is then created. Valid flags handling: The valid flags vector is optional. If no vector is supplied the global flag to use the valid flags is turned off. If supplied it must have the same length as the measurement vector, with 0 meaning that the corresponding measurement is invalid and non-zero that it is valid.

Keywords

convert

Parameters
Name Type Description

values

FLOAT

The vector of measurement values.

coordinates

CONST_AUTO

Optional vector of world coordinates (float or 2D points).

flags

INT

Optional vector of valid flags of the same length as the measurement vector.

Return values
Name Type Description

profile

OBJECT Profile

The new profile.

Sample
local profile = Profile.createFromVector(values, coordinates, flags)
crop()
Short description

Creates a new profile by cropping a segment of another profile. Coordinate system handling: The coordinate representation of the output profile is modified: If an implicit coordinate representation is used, the start coordinate is adjusted. If an explicit representation is used, the coordinate vector is cropped accordingly. Valid flags handling: The valid flags vector is cropped also if it exists.

Keywords

range, sub profile, region

Parameters
Name Type Description

profile

CONST_OBJECT Profile

Input profile

startIndex

INT

The start index, zero-based indexing.

stopIndex

INT

The end index, zero-based indexing.

Return values
Name Type Description

croppedProfile

OBJECT Profile

The new cropped profile. Returns nil if any index is out-of-range or if stop index is smaller than start index.

Sample
local croppedProfile = Profile.crop(profile, startIndex, stopIndex)
difference()
Short description

Calculates the absolute or squared difference between two profiles, sample-wise. The two profiles must have the same number of samples. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.

Keywords

ssd, sad

Parameters
Name Type Description

profile1

CONST_OBJECT Profile

The first source profile.

profile2

CONST_OBJECT Profile

The second source profile.

mode

ENUM DifferenceMode

Absolute or squared difference (ABS or SQUARE).

Return values
Name Type Description

result

OBJECT Profile

The difference profile.

Sample
local result = Profile.difference(profile1, profile2, mode)
differenceInplace()
Short description

In-place version of the Profile.difference function that modifies the input profile. See base function for full documentation.

Keywords

ssd, sad

Parameters
Name Type Description

profile1

OBJECT Profile

The first source profile. This profile is overwritten with the result of the difference.

profile2

CONST_OBJECT Profile

The second source profile.

mode

ENUM DifferenceMode

Absolute or squared difference (ABS or SQUARE).

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.differenceInplace(profile1, profile2, mode)
divide()
Short description

Divides the first profile with the second, sample-wise. The two profiles must have the same number of samples. If division-by-zero occurs, the corresponding output is set to zero. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: The valid flags of the output are enabled if any of the inputs have their flags enabled. Both input profiles must have a valid measurement to produce a valid output for an index. If output valid flags are enabled, division-by-zero sets the corresponding valid flag to false.

Parameters
Name Type Description

profile1

CONST_OBJECT Profile

The first source profile.

profile2

CONST_OBJECT Profile

The second source profile.

Return values
Name Type Description

result

OBJECT Profile

The resulting profile.

Sample
local result = Profile.divide(profile1, profile2)
divideInplace()
Short description

In-place version of the Profile.divide function that modifies the input profile. See base function for full documentation.

See also

Profile.divide

Parameters
Name Type Description

profile1

OBJECT Profile

The first source profile. This profile is overwritten with the result of the division.

profile2

CONST_OBJECT Profile

The second source profile.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.divideInplace(profile1, profile2)
fillInvalidValues()
Short description

Fills in invalid values in a profile using neighboring valid values. A number of different ways interpolation methods are available: LINEAR: Fills invalid values using linear interpolation. Maximum length of invalid value region can be specified with fillParam. N invalid in a row is filled if N is smaller or equal to fillParam. All invalid are filled if fillParam is unspecified. NEIGHBOR_MIN: Fills invalid values with the min value of the two neighboring valid values. NEIGHBOR_MAX: Fills invalid values with the max value of the two neighboring valid values. NEIGHBOR_MEAN: Fills invalid values with the mean value of the two neighboring valid values. Valid flags handling: If no maximum length of invalid regions is specified all invalid values are filled and UseValidFlag is set to false.

Keywords

interpolation, missing data

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

fillMethod

ENUM FillInvalidMethod

Method to use when filling invalid values.

maxGap

INT

Maximum gap of invalid samples to fill. Default: infinite.

Return values
Name Type Description

result

OBJECT Profile

The filled profile.

Sample
local result = Profile.fillInvalidValues(profile, fillMethod, maxGap)
fillInvalidValuesWithReference()
Short description

Fills invalid values with corresponding values in a reference profile. Valid flags handling: All samples in the reference profile is assumed to be valid. Thus, a invalid sample in the input profile is always replaced with corresponding value in the reference profile. UseValidFlag is set to false in result profile.

Keywords

interpolation, missing data

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

referenceProfile

CONST_OBJECT Profile

The reference profile of equal length as the source profile.

Return values
Name Type Description

result

OBJECT Profile

The filled profile.

Sample
local result = Profile.fillInvalidValuesWithReference(profile, referenceProfile)
findEqual()
Short description

Finds elements in a profile equal to a given value, within a give tolerance. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

value, search

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

value

FLOAT

Value to find.

epsilon

FLOAT

Tolerance interval. Default: eps of float32

Return values
Name Type Description

indices

INT

Indices of found elements.

Sample
local indices = Profile.findEqual(profile, value, epsilon)
findLocalExtrema()
Short description

Finds local extreme points (minima or maxima) of a Profile. A point is a local maximum if it is larger than all points within a neighborhood of the specified size. An optional contrast threshold level can be defined that sets a required value difference between the local maximum and the values on each side of the maximum, within the neighborhood. For locally maximal plateaus, where several measurements in the profile have the exact same value, only the leftmost value is reported. An optional absolute threshold can be specified, if so, point values must exceed the absolute threshold to be reported. Local minima are detected in a similar way. If contrastDifferenceMode ONE is selected (default), there must be at least one valid value on each side that is further from the extremal point than contrastThreshold. If contrastDifferenceMode ALL is selected, there must be at least one valid value on each side, and all valid values must be further from the extremal point than contrastThreshold. For non-closed profiles, the entire neighborhood must fit within the profile. E.g., if neighborhoodSize = 5, no extreme points will be detected at the first and last 2 measurements. Closed profiles are handled by wrap-around of the neighborhood. Coordinate system handling: The coordinate representation is not considered in this operation, the indices of the extremal points are returned. Valid flags handling: A maxima or minima can never be reported at positions with invalid data, but invalid data can be contained in the local neighborhood around a reported extreme point. When determining if a point is an extreme point, invalid data points within the local neighborhood are ignored.

Keywords

extreme, local maximum, local minimum, valley, peak

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

extremaType

ENUM ExtremaType

Which type of extrema to look for. MIN or MAX.

neighborhoodSize

INT

The neighborhood size, expressed as number of samples. Must be odd and >= 3. Default is 3.

contrastThreshold

FLOAT

Required height of the peak/valley (value difference between the extreme point and surrounding points). Set to zero to disable (default).

contrastDifferenceMode

ENUM ContrastDifferenceMode

Determines how the difference between the extreme point and the surrounding points is calculated. Default is ONE, there must be at least one valid value on each side that is further from the extremal point than contrastThreshold.

absoluteThreshold

FLOAT

Absolute threshold, extremal points must be beyond this value to be included in the output. By default, this threshold is not used.

Return values
Name Type Description

extremaPositions

INT

Positions of the detected min or max points expressed as sample indices (zero-based). Nil if invalid parameters are provided.

Sample
local extremaPositions = Profile.findLocalExtrema(profile, extremaType, neighborhoodSize, contrastThreshold, contrastDifferenceMode, absoluteThreshold)
findRangeEdges()
Short description

Finds points in a range data profile that are likely to correspond to edges of physical objects. Although this function can be run on profiles from any source, it is developed with range data from laser devices in mind. The algorithm looks for points where the profile has a sharp knee near a discontinuity or fast transition between a low and a high level. A differenceStep parameter determines the width over which the value transition is measured, i.e., Step 1: [1 0 -1], Step 2: [1 0 0 0 -1], and so on. This parameter should be tuned such that the filter spans the entire low-high transition. Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: If side = HIGH, this function reports edge points at transitions between valid and invalid measurements. This is because the low side of a physical 3D edge often contains invalid measurements due to shadowing of the laser line. For edges detected at such transitions between valid and invalid measurements, the minStrength parameter is ignored. If side = LOW, edges are only reported where the non-zero filter coefficients hit valid measurements.

Keywords

corner, discontinuity, step

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

differenceStep

INT

The central difference step.

polarity

ENUM SlopePolarity

Slope polarity. POSITIVE (rising slope) or NEGATIVE (falling slope).

minStrength

FLOAT

Threshold on the magnitude central difference filter response. Only slopes with a strength larger than this threshold are reported.

side

ENUM EdgeSide

Side of the range edge (HIGH or LOW side).

Return values
Name Type Description

subsampleIndex

FLOAT

Index with subsample (float) precision of the found edge points. Nil if invalid parameters are provided.

Sample
local subsampleIdx = Profile.findRangeEdges(profile, differenceStep, polarity, minStrength, side)
fourierTransform()
Short description

Calculates the Fourier transform of a profile. A sampled Fourier transform is returned distributed over one profile with magnitude values and one profile with phase values. The coordinates of the output profiles are adjusted to fit the input profile coordinates. E.g. if the input coordinates are in seconds, the output profile coordinates are in Hertz. If the input coordinates are in meters, the output coordinates are in cycles per meter and so on. The input profile coordinates must be of type implicit 1D (see Profile.setImplicitCoordinates). Missing values are not supported. The input profile can be zero-padded to a given length to increase the apparent frequency resolution of the output. If the transformLength parameter is smaller than the length of the input profile, the full input profile is used and no padding occurs. Set the smoothWindow flag true to apply a smooth window function to the profile prior to transformation. Using a smooth window makes the side lobes decay faster but also makes the main lobe wider and lower, i.e. low amplitude components become easier to detect but frequencies close to each other may merge into the same peak in the amplitude spectrum. Only the positive-frequency half spectrum is returned as the input is a real signal. The output frequency range is from zero to half the sampling frequency 0.5 * 1/T, where T is the sample distance of the input profile (for even size input profiles). N/2 + 1 output samples are created, where N is the number of input samples. If the first sample of the input profile is not at coordinate zero, the output phase is adjusted to match the translation of the input. Magnitude values are normalized to match the DC-level and half the amplitude of pure sinusoidal inputs, i.e. the transform of the profile a + b*sin(2*pi*f*t) will have a magnitude profile with value a at zero and value b/2 at f. Valid flags handling: Only profiles with disabled validity flags are allowed. Raw DFT mode: By setting the rawDFT flag true, most checks of the input and all scaling of the output are removed and a DFT is performed directly on all the values in the input profile. The transformLength parameter is ignored and no smoothed window is used. Coordinates and validity flags are ignored and the output coordinate system is not related to frequencies. The result is returned in Cartesian form, the first profile with the real part and the second profile contains the imaginary part. The full spectrum is returned, the first sample is the DC-component.

Keywords

dft, frequency, spectrum, fft

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

smoothWindow

BOOL

If set, a smooth window function (Hann window) is applied to the profile prior to transformation. Default is false, i.e. a box window is used. Ignored in raw mode.

transformLength

INT

The target transform length, if the input profile is shorter it is zero padded. Ignored in raw mode.

rawDFT

BOOL

Set to true to use raw DFT mode, default is false.

Return values
Name Type Description

magnitude

OBJECT Profile

The magnitude profile. The real part in raw mode.

phase

OBJECT Profile

The phase profile. The imaginary part in raw mode.

Sample
local magnitude, phase = Profile.fourierTransform(profile, smoothWindow, transformLength, rawDFT)
fourierTransformInverse()
Short description

Calculates the inverse Fourier transform. This function is the inverse of fourierTransform(), taking one magnitude profile and one phase profile and calculating the corresponding profile. The input profiles should have the first frequency sample at 0 and the last frequency sample at half the time domain sampling frequency, as created by fourierTransform(). The output is always calculated starting at zero offset and will have 2*(N-1) samples, where N is the number of samples in the input. The output coordinate system matches the input coordinate system, e.g. if the input coordinates are in hertz, the output coordinates are in seconds. If the coordinate systems specified in the magnitude profile and phase profile differ, the magnitude coordinate system is used. Note that this means that the returned profile will always have an even number of samples even if the originally transformed profile had an odd number of samples. Further, this function always recreates the part of the signal starting at time/position zero, which may not be where the original profile was sampled. Valid flags handling: Only profiles with disabled validity flags are allowed. Raw DFT mode: By setting the rawDFT flag true, most checks of the input and all scaling of the output are removed and an IDFT is performed directly on all the values in the input profile. In raw mode, input is expected to be in Cartesian form (first profile is the real part, second profile is the imaginary part) and the full spectrum is expected, starting with the DC component at the first sample. Coordinates and validity flags are ignored and the output coordinate system is not related to the input. The result is returned in Cartesian form, the first profile with the real part and the second profile contains the imaginary part.

Keywords

frequency, idft, spectrum, ifft

Parameters
Name Type Description

magnitude

CONST_OBJECT Profile

The input magnitude profile. The real part in raw mode.

phase

CONST_OBJECT Profile

The input phase profile. The imaginary part in raw mode.

rawDFT

BOOL

Set to true to use raw DFT mode, default is false.

Return values
Name Type Description

profile

OBJECT Profile

The resulting profile. The real part of the result in raw mode.

imaginaryPart

OBJECT Profile

Only used in raw mode, the imaginary part of the result.

Sample
local profile, imaginaryPart = Profile.fourierTransformInverse(magnitude, phase, rawDFT)
gauss()
Short description

Smooths a profile using a Gauss filter kernel. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Only the valid measurements are considered in the calculation. By default, all invalid measurements will be marked as invalid also in the output. If the fill flag is set to true, invalid measurements will be filled with filtered neighbor values where possible.

Keywords

filter, low pass, lp, smooth

Parameters
Name Type Description

profile

CONST_OBJECT Profile

Input profile.

kernelSize

INT

Size of the kernel, must be positive, odd and smaller than the profile length.

fillInvalid

BOOL

Optional flag to also fill in invalid values while filtering. Default is false.

Return values
Name Type Description

smoothProfile

OBJECT Profile

Output profile, smoothed by the Gauss filter.

Sample
local smoothProfile = Profile.gauss(profile, kernelSize)
gaussDerivative()
Short description

Differentiates a profile using a Gaussian derivative filter kernel. The filter is normalized such that the overall magnitude of the output is independent of the filter size. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Invalid flags are not allowed in this operation.

Keywords

first, slope

Parameters
Name Type Description

profile

CONST_OBJECT Profile

Input profile.

kernelSizeSamples

INT

Size of the kernel, must be positive and odd.

order

ENUM DifferentiationOrder

FIRST gives first order derivative and SECOND gives second order derivative.

Return values
Name Type Description

derivativeProfile

OBJECT Profile

Output profile, differentiated by the Gaussian derivative filter.

Sample
local derivativeProfile = Profile.gaussDerivative(profile, kernelSizeSamples, order)
getArea()
Short description

Returns estimate of the signed area of the measurements in the profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. Signed area: Negative values contribute with negative area. Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

riemann, integral

See also

Profile.getSum

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile or vector of profiles.

Return values
Name Type Description

area

FLOAT

The estimated area.

validCount

INT

The number of valid measurements per profile.

Sample
local area, validCount = Profile.getArea(profile)
getClosed()
Short description

Returns if the closed flag is enabled. If the flag is enabled, the profile is considered closed, meaning that the first measurement follows after the last. This affects the border handling of some operations such as filtering algorithms.

Keywords

circular, infinite, periodic

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile object.

Return values
Name Type Description

isClosed

BOOL

Indicating if the profile is closed.

Sample
local isClosed = Profile.getClosed(profile)
getCoordinate()
Short description

Returns the coordinates of the given index or vector of indexes.

Keywords

location, position, spatial

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile object.

index

INT

The index or vector of indexes. Zero-based indexing.

Return values
Name Type Description

coordinate

AUTO

The world coordinate(s), a (vector of) floating point number(s) for 1D coordinates and a (vector of) 2D point(s) for 2D coordinates. Returns nil if any index is out-of-range.

Sample
local coordinate = Profile.getCoordinate(profile, index)
getCoordinateType()
Short description

Return the used coordinate representation type. Possible coordinate types: IMPLICIT_1D, EXPLICIT_1D, IMPLICIT_2D, EXPLICIT_2D.

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile object.

Return values
Name Type Description

coordinateType

ENUM CoordinateType

The coordinate type.

Sample
coordinateType = Profile.getCoordinateType(profile)
getDistance()
Short description

Returns the Euclidian distances between two specified profile elements. Two distances are returned, one along the coordinate axis and one between the two points represented by the (coordinate, value) pairs. For example, if the coordinates represent 2D points, the distances are calculated as follows respectively: coordinage distance: sqrt(dX^2 + dY^2) total distance: sqrt(dX^2 + dY^2 + dValue^2)

Keywords

euclidian

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile object.

index1

INT

Index of sample 1 or vector with indices.

index2

INT

Index of sample 2 or vector with indices..

Return values
Name Type Description

coordDist

FLOAT

Distance in the coordinate dimensions (Euclidean distance).

totalDist

FLOAT

Distance in the value + coordinate dimensions (Euclidean distance).

Sample
local coordDist, totalDist = Profile.getDistance(profile, index1, index2)
getHistogram()
Short description

Returns the histogram of the values in a profile or a set of profiles. The bin centers are returned as the coordinates in the result profile. Values outside the bins (minValue,maxValue) are discarded. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

distribution, statistics

Parameters
Name Type Description

profiles

CONST_OBJECT Profile

The source profiles.

binCount

INT

The number of bins to be used in the histogram. If no value is specified the default number of bins (32) is used.

minValue

FLOAT

The minimum value of the histogram. If no value is specified an automatic value based on the minimum value of all profiles will be used.

maxValue

FLOAT

The maximum value of the histogram. If no value is specified an automatic value based on the maximum value of all profiles will be used.

Return values
Name Type Description

histogram

OBJECT Profile

Histogram, represented as a profile. The profile coordinates is the center of each histogram bin.

Sample
local histogram = Profile.getHistogram(profiles, binCount, minValue, maxValue)
getIntersectionAngle()
Short description

Measures angle between two lines fitted around a given position in the input profile. One line is fitted to samples to the left of the given position and the other to the right using a robust RANSAC least squares fitting. The measured angle is between 0 and 2*PI, and is measured above the profile. Thus, a valley ( \/ ) gives an angle smaller than PI and a peak ( /\ ) an angle larger than PI (if \/ = a then /\ = 2*PI - a). Coordinate system handling: The coordinate are considered in the line fitting operation. The coordinate system of the profile must be 1D. Valid flags handling: Only valid values from the input profiles are used.

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

position

INT

Position to estimate lines around expressed as a sample index.

regionSize

INT

Size of region(s), expressed in samples, to the left and right of the given position to use for line fitting. With a scalar input the left and right regions are of equal size. If vector the first value is the size of the left region and the second the size of the right region.

skipSize

INT

Skip samples before the region start to produce a gap to the given position for the line fitting. With a vector input, a different number of samples can be skipped to the left and right respectively.

iterations

INT

Number of iterations in the RANSAC loop in the line fitting. Default value is 200. Can be reduced if there are few or no outliers.

Return values
Name Type Description

angleRad

FLOAT

Intersection angle, in radians.

intersectionPoint

OBJECT Point

Intersection point of the lines, expressed as a 2D Point using (coordinate, value) as components.

leftLine

OBJECT Profile.Curve

Left line.

rightLine

OBJECT Profile.Curve

Right line.

Sample
local angleRad, intersectionPoint, leftLine, rightLine = Profile.getIntersectionAngle(profile, position, regionSize, skipSize, iterations)
getMax()
Short description

Returns the maximum value of a profile. In addition, the (first) index and the number of valid measurements are also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both maxValue and validCount. Start and stop indices (inclusive) can be used to calculate the maximum on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

maximum

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile or vector of profiles.

startIndex

INT

Start index of search range.

stopIndex

INT

Stop index of search range.

Return values
Name Type Description

maxValue

FLOAT

The maximum value for each input profile.

index

INT

The (first) index at which the maximum value is located. Vector output if a vector of profiles is given as input.

validCount

INT

The number of valid measurements per input profile.

Sample
local maxValue, index, validCount = Profile.getMax(profile)
getMean()
Short description

Returns the mean value of a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both meanValue and validCount. Start and stop indices (inclusive) can be used to calculate the mean on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

statistics, average

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile or vector of profiles.

startIndex

INT

Start index of search range.

stopIndex

INT

Stop index of search range.

Return values
Name Type Description

meanValue

FLOAT

The mean value, one value for each profile.

validCount

INT

The number of valid elements per profile.

Sample
local meanValue, validCount = Profile.getMean(profile)
getMedian()
Short description

Returns the median value of a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both medianValue and validCount. Start and stop indices (inclusive) can be used to calculate the median on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

statistics, percentile

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile or vector of profiles.

startIndex

INT

Start index of search range.

stopIndex

INT

Stop index of search range.

Return values
Name Type Description

medianValue

FLOAT

The median value, one value for each profile.

validCount

INT

The number of valid measurements per profile.

Sample
local medianValue, validCount = Profile.getMedian(profile)
getMin()
Short description

Returns the minimum value of a profile. In addition, the (first) index and the number of valid measurements are also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both minValue and validCount. Start and stop indices (inclusive) can be used to calculate the minimum on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

minimum

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile or vector of profiles.

startIndex

INT

Start index of search range.

stopIndex

INT

Stop index of search range.

Return values
Name Type Description

minValue

FLOAT

The minimum value for each input profile.

index

INT

The (first) index at which the minimum value is located. Vector output if a vector of profiles is given as input.

validCount

INT

The number of valid measurements per input profile.

Sample
local minValue, index, validCount = Profile.getMin(profile)
getSize()
Short description

Returns the number of measurements in the profile.

Keywords

width, length

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile object.

Return values
Name Type Description

size

INT

The number of measurements in the profile.

Sample
local size = Profile.getSize(profile)
getStandardDeviation()
Short description

Returns both the mean and standard deviation of the measurements in a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for meanValue, stdDev and validCount. Start and stop indices (inclusive) can be used to calculate the standard deviation on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

statistics, variance

Parameters
Name Type Description

profiles

CONST_OBJECT Profile

The source profile or vector of profiles.

startIndex

INT

Start index of search range.

stopIndex

INT

Stop index of search range.

Return values
Name Type Description

meanValue

FLOAT

The mean value for each profile.

stdDev

FLOAT

The standard deviation (maximum likelihood estimate), for each profile.

validCount

INT

The number of valid measurements per profile.

Sample
local meanValue, stdDev, validCount = Profile.getStandardDeviation(profile)
getSum()
Short description

Returns the sum of the measurement of a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. Zero is returned for profiles without valid data. Start and stop indices (inclusive) can be used to calculate the sum on a part of the profile(s). Valid flags handling: Only the valid measurements are considered in the calculation.

Keywords

integral, statistics, summation, total

See also

Profile.getArea

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile or vector of profiles.

startIndex

INT

Start index of search range.

stopIndex

INT

Stop index of search range.

Return values
Name Type Description

sum

FLOAT

The sum, one sum for each profile.

validCount

INT

The number of valid measurements per profile.

Sample
local sumValue, validCount = Profile.getSum(profile)
getValidCount()
Short description

Get the number of valid elements in a profile or set of profiles, one count for each profile is returned. If valid flags are not used validCount = profile.Size().

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile or profiles.

Return values
Name Type Description

validCount

INT

Number of valid elements.

Sample
 local validCount = Profile.getValidCount(profile)
getValidFlag()
Short description

Returns the valid flag of the measurements at the given index or vector of indexes.

Keywords

missing data

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile object.

index

INT

The index or vector of indexes. Zero-based indexing.

Return values
Name Type Description

flag

INT

The valid flag. 0 means invalid data and non-zero valid data. Returns nil if any index is out-of-range.

Sample
local flag = Profile.getValidFlag(profile, index)
getValidFlagsEnabled()
Short description

Checks if global usage of valid flags is enabled. 'False' means that all measurement values are treated as valid regardless of the valid flags vector. 'True' means that the valid flag is regarded for each measurement.

Keywords

missing data

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile object.

Return values
Name Type Description

validFlagsEnabled

BOOL

Indicating if the valid flags are enabled.

Sample
local validFlagsEnabled = Profile.getValidFlagsEnabled(profile)
getValue()
Short description

Returns the measurement values of a profile at the provided index or indexes.

Keywords

sample, element

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile object.

index

INT

The index or vector if indexes to get. Zero-based indexing.

Return values
Name Type Description

value

FLOAT

The value(s). Returns nil if any index is out-of-range.

Sample
local value = Profile.getValue(profile, index)
interpolateCoordinate()
Short description

Returns coordinate(s) which are linearly interpolated between the two closest indexes in the profile. Coordinate system handling: The function returns 2D Points for profiles with 2D coordinates and floats for profiles with 1D coordinates. Valid flags handling: Valid flags are not considered in this function.

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile.

indexFloat

FLOAT

Index or indexes in floating point precision. Zero-based indexing.

Return values
Name Type Description

coordinate

AUTO

The world coordinate(s) as a single value/point or as a vector of values/points. Returns nil if any index is out-of-range.

Sample
local coordinate = Profile.interpolateCoordinate(profile, indexFloat)
load()
Short description

Imports a profile from the specified file path. The format is defined by the file extension: .csv: Comma-separated value file .json: JSON (native AppSpace format) .msgpack: MessagePack (native AppSpace format) The csv-file should have numbers written as text, separated by at least one character that is not normally used in numbers (e.g. tab, semicolon, colon, etc.). Only decimal points are accepted, commas are interpreted as delimiters between entries. Values like -1.555e-3 are accepted. Regular spaces are ignored. The first row is taken as values for the profile. If the second row is equal in length, those numbers are interpreted as validity flags (zero means invalid, nonzero means valid). If the third row is equal in length, those numbers are interpreted as coordinates for the samples. Coordinates should be monotonically increasing. Coordinate system handling: If no coordinate row of correct length is present, the coordinate representation will be implicit 1D, starting at 0 with a delta value of 1. If the coordinate row is valid, coordinates will be as given in the third row and of type explicit 1D. Valid flags handling: If no validity row of correct length is present, all measurements are considered as valid. No valid flags vector is created. If the validity mask row is present, the validity flags are set as given in the second row.

Keywords

import, csv

See also

File, Object.load

Parameters
Name Type Description

filepath

STRING

The path and name of the file to load the profile from.

Return values
Name Type Description

profile

OBJECT Profile

The new profile or nil on failure.

Sample
local profile = Profile.load("private/profile.csv")
median()
Short description

Smooths a profile using a median filter. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Only the valid measurements are considered in the calculation. There is an option to fill in invalid values in the filter operation.

Keywords

filter, smooth

Parameters
Name Type Description

profile

CONST_OBJECT Profile

Input profile.

kernelSize

INT

Size of the kernel, must be positive, odd and smaller than the profile length.

fillInvalid

BOOL

Optional flag to also fill in invalid values while filtering. Default is false.

Return values
Name Type Description

smoothProfile

OBJECT Profile

Output profile, filtered by the median filter.

Sample
local smoothProfile = Profile.median(profile, kernelSize)
mirror()
Short description

Mirrors the values and valid flags in the profile, so that the first sample is placed last and last sample placed first in the output profile. Note that the coordinates are not mirrored.

Keywords

flip

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

Return values
Name Type Description

result

OBJECT Profile

Mirrored profile.

Sample
local result = Profile.mirror(profile)
mirrorInplace()
Short description

In-place version of mirror that modifies the input profile. See base function for full documentation.

Keywords

flip

See also

Profile.mirror

Parameters
Name Type Description

profile

OBJECT Profile

The source profile and result profile.

Return values
Name Type Description

result

OBJECT Profile

Reference to the mirrored profile.

Sample
local result = Profile.mirrorInplace(profile)
multiply()
Short description

Multiplies two profiles sample-wise. The two profiles must have the same number of measurements. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.

Keywords

times

Parameters
Name Type Description

profile1

CONST_OBJECT Profile

The first source profile.

profile2

CONST_OBJECT Profile

The second source profile.

Return values
Name Type Description

result

OBJECT Profile

The product profile.

Sample
local result = Profile.multiply(profile1, profile2)
multiplyAddConstant()
Short description

Multiplies one profile with alpha, thereafter the constant beta is added. If the multiplication underflows/overflows, the result is underflow/overflow, regardless of the addition. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

alpha

FLOAT

The constant to multiply with.

beta

FLOAT

The constant to add.

Return values
Name Type Description

result

OBJECT Profile

The resulting profile.

Sample
local result = Profile.multiplyAddConstant(profile, alpha, beta)
multiplyAddConstantInplace()
Short description

In-place version of the Profile.multiplyAddConstant function that modifies the input profile. See base function for full documentation.

Parameters
Name Type Description

profile1

OBJECT Profile

The first source profile. This profile is overwritten with the result of the multiplication and sum.

alpha

FLOAT

The constant to multiply with.

beta

FLOAT

The constant to add.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.multiplyAddConstantInplace(profile1, alpha, beta)
multiplyConstant()
Short description

Multiplies a profile with a constant. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

scale

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

constant

FLOAT

The constant to multiply the samples with.

Return values
Name Type Description

result

OBJECT Profile

The multiplied profile.

Sample
local result = Profile.multiplyConstant(profile, constant)
multiplyConstantInplace()
Short description

In-place version of the Profile.multiplyConstant function that modifies the input profile. See base function for full documentation.

Keywords

scale

Parameters
Name Type Description

profile1

OBJECT Profile

The first source profile. This profile is overwritten with the result of the multiplication.

constant

FLOAT

The constant to multiply the samples with.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.multiplyConstantInplace(profile1, constant)
multiplyInplace()
Short description

In-place version of the Profile.multiply function that modifies the input profile. See base function for full documentation.

Keywords

times

Parameters
Name Type Description

profile1

OBJECT Profile

The first source profile. This profile is overwritten with the result of the multiplication.

profile2

CONST_OBJECT Profile

The second source profile.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.multiplyInplace(profile1, profile2)
pow()
Short description

Raises each measurement value to the power of an exponent. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.

Keywords

exponential, square, squared, power

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

exponent

FLOAT

The exponent.

Return values
Name Type Description

result

OBJECT Profile

The resulting profile.

Sample
local result = Profile.pow(profile, exponent)
powInplace()
Short description

In-place version of the Profile.pow function that modifies the input profile. See base function for full documentation.

Keywords

exponential, square, squared, power

See also

Profile.pow

Parameters
Name Type Description

profile

OBJECT Profile

The source profile. This profile is overwritten with the result of the pow.

exponent

FLOAT

The exponent.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.powInplace(profile, exponent)
removeValidFlagVector()
Short description

Remove the valid flag vector from the profile.

Parameters
Name Type Description

profile

OBJECT Profile

The profile object.

Sample
 Profile.removeValidFlagVector(profile)
resize()
Short description

Samples the profile using the given number of samples and outputs these as a new profile. Linear interpolation is used. Both input and output profiles must have at least two samples. The new samples are placed equidistantly. For explicit 2D coordinates, the distance along the coordinate polygon is used. All input samples must have unique positions. Explicit 1D coordinates in the input profile must be strictly monotonic. Coordinate system handling: Implicit 1D coordinates are used for the output when the input coordinates are 1D (implicit or explicit). For 2D coordinates, the output coordinate type is the same as the input coordinate type. The closedness of the profile is taken into account when placing the new samples in all cases except for explicit 1D coordinates, where the wrap-around point is undefined. Valid flags handling: Valid flags are respected. Any output sample where at least one of the input samples used for interpolation is invalid, is marked as invalid.

Keywords

decimate, equidistant, interpolate, scale, subsample, resample

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile to resize.

newSize

INT

The desired size of the new profile in samples.

Return values
Name Type Description

newProfile

OBJECT Profile

The new profile, or nil on error.

Sample
local newProfile = Profile.resize(profile, newSize)
resizeScale()
Short description

Samples the profile using the given scale factor of samples in relation to the number of samples in the input profile. E.g. a factor 2 generates twice as many samples in the new profile. Linear interpolation is used. Both input and output profiles must have at least two samples. The new samples are placed equidistantly. For explicit 2D coordinates, the distance along the coordinate polygon is used. All input samples must have unique positions. Explicit 1D coordinates in the input profile must be strictly monotonic. Coordinate system handling: Implicit 1D coordinates are used for the output when the input coordinates are 1D (implicit or explicit). For 2D coordinates, the output coordinate type is the same as the input coordinate type. The closedness of the profile is taken into account when placing the new samples in all cases except for explicit 1D coordinates, where the wrap-around point is undefined. Valid flags handling: Valid flags are respected. Any output sample where at least one of the input samples used for interpolation is invalid, is marked as invalid.

Keywords

decimate, equidistant, interpolate, scale, subsample, resample

See also

Profile.resize

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile to resize.

factor

FLOAT

Resize factor, e.g, 0.5 or 2.0.

Return values
Name Type Description

newProfile

OBJECT Profile

The new profile, or nil on error.

Sample
local newProfile = Profile.resizeScale(profile, factor)
rotate()
Short description

Rotates a profile in the value-coordinate plane. Only 1D coordinates are supported. Result is always in EXPLICIT_1D coordinates.

Keywords

transform

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

rotationRad

FLOAT

Rotation in radians. A positive rotation is in the counterclockwise direction.

coordinateOrigin

FLOAT

Optional origin of rotation in the coordinate dimension. Default: 0.0

valueOrigin

FLOAT

Optional origin of rotation in the value dimension. Default: 0.0

Return values
Name Type Description

result

OBJECT Profile

Rotated profile. EXPLICIT_1D coordinates.

Sample
local result = Profile.rotate(profile, rotationRad, coordinateOrigin, valueOrigin)
rotateInplace()
Short description

In-place version of rotate. Only 1D coordinates are supported. Result is always in EXPLICIT_1D coordinates.

Keywords

transform

Parameters
Name Type Description

profile

OBJECT Profile

The profile to rotate. This profile is overwritten with the result of the rotation.

rotationRad

FLOAT

Rotation in radians. A positive rotation is in the counter clockwise direction.

coordinateOrigin

FLOAT

Optional origin of rotation in the coordinate dimension. Default: 0.0

valueOrigin

FLOAT

Optional origin of rotation in the value dimension. Default: 0.0

Return values
Name Type Description

result

OBJECT Profile

Reference to the rotated profile. EXPLICIT_1D coordinates.

Sample
local result = Profile.rotateInplace(profile, rotationRad, coordinateOrigin, valueOrigin)
save()
Short description

Writes a profile to the specified file path. Overwrites the file if it already exists. The format is defined by the file extension: .csv: Comma-separated value file, using a semicolon as separator. .json: JSON (native AppSpace format) .msgpack: MessagePack (native AppSpace format) For the csv-file format the first line contains the profile values. If the validity flags are active, the second line contains the flags (0 means invalid, 1 means valid). If coordinates are explicit 1D, the third line contains the coordinate of each sample. Coordinate system handling: Only 1D coordinates are supported. Implicit coordinates are not written to the file. Explicit coordinates are written to the third line in the output file. Valid flags handling: If the validity flags are active, those are written to the second line in the output file.

Keywords

export, csv

See also

File, Object.save

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile to store.

filepath

STRING

The path and name of the file to write the profile to.

Return values
Name Type Description

success

BOOL

True on success, false on write error, nil if the call was malformed.

Sample
local success = Profile.save(profile, "private/profile.csv")
setClosed()
Short description

Sets the closed flag. If the flag is enabled, the profile is considered closed, meaning that the first measurement follows after the last. This affects the border handling of some algorithms. This operation does not affect any values, coordinates of measurements or valid flags.

Keywords

circular, infinite, periodic

Parameters
Name Type Description

profile

OBJECT Profile

The profile object.

setClosed

BOOL

Marking the profile as closed (true) or as open (false).

Sample
Profile.setClosed(profile, true)
setCoordinate()
Short description

Sets the coordinates of the given index or indexes. The dimensionality of the new coordinates must match those of the profile, e.g. only 2D coordinates can be set in a profile already using 2D coordinates. If the coordinate representation of the profile is implicit, it is silently converted to an explicit representation before updating coordinates. Use setImplicitCoordinates to setup an implicit coordinate system.

Keywords

location, position, spatial

Parameters
Name Type Description

profile

OBJECT Profile

The profile object.

index

INT

The index or vector of indexes. Zero-based indexing. Out-of-range indexes are ignored.

coordinate

CONST_AUTO

The world coordinates, a (vector of) floating point number(s) for 1D coordinates and a (vector of) 2D point(s) for 2D coordinates. The vector must be of the same length as the index vector.

Sample
Profile.setCoordinate(profile, index, coordinate)
setImplicitCoordinates()
Short description

Sets the coordinates of the profile to implicit type (the coordinates of the first sample and a difference between samples). Provide two floating point numbers to set 1D coordinates, or two 2D points to set 2D coordinates. Use setCoordinate to set explicit coordinates of specific samples.

Keywords

location, position, spatial

Parameters
Name Type Description

profile

OBJECT Profile

The profile object.

start

CONST_AUTO

The coordinates of the first sample, a scalar value or 2D Point.

delta

CONST_AUTO

The difference in position of each two consecutive samples, a scalar value or 2D Point.

Sample
Profile.setImplicitCoordinates(profile, start, delta)
setValidFlag()
Short description

Set the valid flags of a profile at the given index or vector of indexes. Sets the flags in the input profile (in-place).

Keywords

missing data

Parameters
Name Type Description

profile

OBJECT Profile

The profile object.

index

INT

The index or vector of indexes. Zero-based indexing. Out-of-range indexes are ignored.

flag

INT

The valid flag to set to the indices. 0 means invalid and non-zero means valid.

Sample
Profile.setValidFlag(profile, index, flag)
setValidFlagRange()
Short description

Set a range of valid flags in the input profile (inplace). Sets all valid flags between startIndex and stopIndex to the specified flag. If stopIndex is omitted all flags from startIndex to the end of the profile is set.

Parameters
Name Type Description

profile

OBJECT Profile

The profile object.

flag

INT

The valid flag or vector of valid flags, to set to the indices. 0 means invalid and non-zero means valid.

startIndex

INT

Start index or vector of start indices. Zero-based indexing.

stopIndex

INT

Stop index or vector of stop indices. Zero-based indexing. Optional.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
result = Profile.setValidFlagRange(profile, flag, startIndex, stopIndex)
setValidFlagsEnabled()
Short description

Enables or disables the individual valid flag of each measurement. 'False' means that all measurement values are treated as valid regardless of the valid flags set. 'True' means that the valid flag is regarded for each measurement. If the flags are enabled and the profile did not contain a valid flags vector, the vector is generated.

Keywords

missing data

Parameters
Name Type Description

profile

OBJECT Profile

The profile object.

validFlagsEnabled

BOOL

Activating or deactivating the usage of the valid data flags vector.

Sample
Profile.setValidFlagsEnabled(profile, validFlagsEnabled)
setValue()
Short description

Set a measurement value in a profile at one or multiple given position(s). Out-of-range indexes are ignored.

Keywords

sample, element

Parameters
Name Type Description

profile

OBJECT Profile

The profile object.

index

INT

The index or indexes to set. Zero-based indexing.

value

FLOAT

The measurement value to set.

Sample
Profile.setValue(profile, index, value)
shrink()
Short description

Sets all values within a threshold of a given level to that level. For example, with the default level zero, all values within +/- a threshold are set to zero. In denoising context, this is known as a shrinkage operation or hard thresholding. Coordinate system handling: The coordinate representation is copied to the output profile. Valid flags handling: Valid flags are copied to the output.

Keywords

denoise, hard thresholding, soft thresholding, clamp

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The input profile.

threshold

FLOAT

Values within this distance of level is set to level.

level

FLOAT

The level to shrink around, default is zero.

Return values
Name Type Description

newProfile

OBJECT Profile

The new profile, or nil on error.

Sample
local newProfile = Profile.shrink(profile, threshold, level)
shrinkInplace()
Short description

Inplace version of the shrink function that modifies the input profile. See the base function for full documentation.

Keywords

denoise, hard thresholding, soft thresholding, clamp

Parameters
Name Type Description

profile

OBJECT Profile

The profile.

threshold

FLOAT

Values within this distance of level is set to level.

level

FLOAT

The level to shrink around, default is zero.

Sample
Profile.shrinkInplace(profile, threshold, level)
sort()
Short description

Sort a profile with respect to sample values or coordinates. The validity flags and explicit coordinates follow the samples while sorting. Implicit coordinates are unaffected by sorting. When sorting by coordinates, explicit 1D coordinates must be used. A stable sorting algorithm is used, such that samples with equal value do not change order internally. Invalid values are sorted as if marked as valid, but their invalidity flag is kept.

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

ascending

BOOL

True if profile is to be sorted in ascending order. Optional, default is true.

key

ENUM SortKey

Indicates if samples are to be sorted by value or by coordinate. Optional, default is sorting by value.

Return values
Name Type Description

result

OBJECT Profile

Sorted profile.

index

INT

Vector of indices indicating the effect of the sorting operation. The first entry indicates what sample in the input that ended up first in the output. Indices are zero-based.

Sample
local result, index = Profile.sort(profile, ascending, key)
subtract()
Short description

Subtracts the second profile from the first, sample-wise. The two profiles must have the same number of samples. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.

Keywords

minus

Parameters
Name Type Description

profile1

CONST_OBJECT Profile

The first source profile.

profile2

CONST_OBJECT Profile

The second source profile.

Return values
Name Type Description

result

OBJECT Profile

The difference profile.

Sample
local result = Profile.subtract(profile1, profile2)
subtractInplace()
Short description

In-place version of the Profile.subtract function that modifies the input profile. See base function for full documentation.

Keywords

minus

Parameters
Name Type Description

profile1

OBJECT Profile

The first source profile. This profile is overwritten with the result of the difference.

profile2

CONST_OBJECT Profile

The second source profile.

Return values
Name Type Description

result

OBJECT Profile

Reference to the result profile.

Sample
local result = Profile.subtractInplace(profile1, profile2)
threshold()
Short description

Return the indices of all valid profile values between the upper and lower threshold. Any threshold can be left out, in which case it has no influence on the selection. Coordinate system handling: The positions of the samples do not influence the function. Missing data handling: Only valid samples are included in the output.

Keywords

region, segmentation

Parameters
Name Type Description

profile

CONST_OBJECT Profile

Input profile.

lowerThreshold

FLOAT

Lower threshold. Optional, default is no lower threshold (no lower limit on sample value).

upperThreshold

FLOAT

Upper threshold. Optional, default is no upper threshold (no upper limit on sample value).

Return values
Name Type Description

indices

INT

Zero-based indices to all valid samples between the upper and lower threshold.

Sample
local indices = Profile.threshold(profile, lowerThreshold, upperThreshold)
toImage()
Short description

Convert a vector of profiles to an image, stacked vertically. The coordinates in the profiles are not used. Valid flags handling: If any of the input profiles has valid flags enabled, the resulting image will have missing data enabled. In that case, any pixel corresponding to an invalid sample in the profile will be stored as missing data in the image.

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile or vector of profiles.

type

ENUM ImageType

The pixel type of the resulting image.

pixelSizeZ

FLOAT

The pixel size in the z-dimension in world coordinates, e.g., the number of millimeters each pixel value integer increment corresponds to. (Default value: 1.0). By selecting 0.0 the scale will be automatically selected.

minZ

FLOAT

The smallest value that is represented in the output image. (Default value: 0.0).

Return values
Name Type Description

result

OBJECT Image

Resulting image.

Sample
local result = Profile.toImage(profile, type, pixelSizeZ, minZ)
toString()
Short description

Gets a user-friendly string description of the profile.

Keywords

description, help, print

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile object.

Return values
Name Type Description

str

STRING

User-friendly description of the profile.

Sample
local str = Profile.toString(profile)
toVector()
Short description

Returns the measurement values, coordinates and valid flags of a profile as vectors. Coordinate system handling: A coordinate vector of the same length as the measurement vector is returned. If the coordinate representation is of implicit type, the vector is calculated. Valid flags handling: If the valid flags are disabled, no flags are returned.

Keywords

convert

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The profile.

Return values
Name Type Description

values

FLOAT

The vector of measurement values, or nil if the profile is not valid.

coordinates

CONST_AUTO

Vector of world coordinates (floats or 2D points), nor nil if the profile is not valid.

flags

INT

Vector of valid data flags, or nil if the flags are not enabled.

Sample
local values, coordinates, flags = Profile.toVector(profile)
translate()
Short description

Translates a profile in the coordinate dimension and/or in the value dimension. Only 1D coordinates are supported.

Keywords

move, shift, transform

Parameters
Name Type Description

profile

CONST_OBJECT Profile

The source profile.

coordinateTranslation

FLOAT

Translation of coordinates.

valueTranslation

FLOAT

Translation of values.

Return values
Name Type Description

result

OBJECT Profile

Translated profile.

Sample
local result = Profile.translate(profile, coordinateTranslation, valueTranslation)
translateInplace()
Short description

In-place version of translate, see base function for full documentation.

Keywords

move, shift, transform

Parameters
Name Type Description

profile

OBJECT Profile

The profile to translate. This profile is overwritten with the translated profile.

coordinateTranslation

FLOAT

Translation of coordinates.

valueTranslation

FLOAT

Translation of values.

Return values
Name Type Description

result

OBJECT Profile

Reference to the translated profile.

Sample
local result = Profile.translateInplace(profile, coordinateTranslation, valueTranslation)

Profile.Curve

Short description

A data type for representing parametric curves and functions such as polynomial and exponential functions. Different families of functions are available.

Keywords

analytic, exponential, fitting, function, gauss, line, parametric, trend, polynomial

Functions

clone()
Short description

Create an independent copy of this curve.

Keywords

copy

Parameters
Name Type Description

inputCurve

CONST_OBJECT Profile.Curve

The curve to clone.

Return values
Name Type Description

outputCurve

OBJECT Profile.Curve

The new copy.

Sample
outputCurve = Profile.Curve.clone(inputCurve)
createExponential()
Short description

Create an exponential curve. f(x) = scale*exp(exponent*x) + offset.

Parameters
Name Type Description

scale

FLOAT

Linear scaling of the curve.

exponent

FLOAT

Exponent.

offset

FLOAT

Constant offset of the curve.

Return values
Name Type Description

expCurve

OBJECT Profile.Curve

The created exponential curve.

Sample
expCurve = Profile.Curve.createExponential(scale, exponent, offset)
createGaussian()
Short description

Create a Gaussian curve. f(x) = scale*exp(-x-mean)^2) / (2*sigma^2 + offset.

Parameters
Name Type Description

scale

FLOAT

Linear scaling of the curve.

mean

FLOAT

Mean (symmetry axis of generated function).

sigma

FLOAT

Standard deviation (width of lobe).

offset

FLOAT

Constant offset of the curve.

Return values
Name Type Description

gaussCurve

OBJECT Profile.Curve

The created Gaussian curve.

Sample
gaussCurve = Profile.Curve.createGaussian(scale, mean, sigma, offset)
createLine()
Short description

Create a line f(x) = offset + slope*x with the specified offset and slope. This is equivalent to creating a first order polynomial.

Parameters
Name Type Description

offset

FLOAT

Offset of line, value at x = 0.

slope

FLOAT

Slope of line, dy/dx.

Return values
Name Type Description

line

OBJECT Profile.Curve

The created line.

Sample
line = Profile.Curve.createLine(offset, slope)
createPolynomial()
Short description

Create a polynomial curve with the specified coefficients. The first coefficient is the constant term, the second is for the linear term and so on.

Parameters
Name Type Description

coefficients

FLOAT

Coefficients a, b, c, …​ in a + b*x + c*x^2 + …​

Return values
Name Type Description

polyCurve

OBJECT Profile.Curve

The created polynomial curve.

Sample
polyCurve = Profile.Curve.createPolynomial(coefficients)
getDerivative()
Short description

Return the derivative of the curve if it can be expressed by any available curve type.

Parameters
Name Type Description

curve

CONST_OBJECT Profile.Curve

The curve to take the derivative of.

Return values
Name Type Description

derivativeCurve

OBJECT Profile.Curve

The derivative of the curve.

Sample
derivativeCurve = Profile.Curve.getDerivative(curve)
getExponentialParameters()
Short description

Returns the parameters of an exponential curve, f(x) = scale*exp(exponent*x) + offset.

Parameters
Name Type Description

expCurve

CONST_OBJECT Profile.Curve

The exponential curve.

Return values
Name Type Description

scale

FLOAT

Linear scaling of the curve.

exponent

FLOAT

Exponent.

offset

FLOAT

Constant offset of the curve.

Sample
scale, exponent, offset = Profile.Curve.getExponentialParameters(expCurve)
getGaussianParameters()
Short description

Returns the parameters of a Gaussian curve, f(x) = scale*exp(-x-mean)^2) / (2*sigma^2 + offset.

Parameters
Name Type Description

gaussCurve

CONST_OBJECT Profile.Curve

The Gaussian curve.

Return values
Name Type Description

scale

FLOAT

Linear scaling of the curve.

mean

FLOAT

Mean (symmetry axis of generated function).

sigma

FLOAT

Standard deviation (width of lobe).

offset

FLOAT

Constant offset of the curve.

Sample
scale, mean, sigma, offset = Profile.Curve.getGaussianParameters(gaussCurve)
getLineParameters()
Short description

Returns the offset and slope of a line.

Parameters
Name Type Description

line

CONST_OBJECT Profile.Curve

The line.

Return values
Name Type Description

offset

FLOAT

Offset of line, value at x = 0.

slope

FLOAT

Slope of line, dy/dx.

Sample
offset, slope = Profile.Curve.getLineParameters(line)
getPolynomialParameters()
Short description

Returns the coefficients of a polynomial curve. The first coefficient is the constant term, the second is for the linear term and so on.

Parameters
Name Type Description

polyCurve

CONST_OBJECT Profile.Curve

The polynomial curve.

Return values
Name Type Description

coefficients

FLOAT

Coefficients a, b, c, …​ in a + b*x + c*x^2 + …​

Sample
coefficients = Profile.Curve.getPolynomialParameters(polyCurve)
getType()
Short description

Return the type of function that represents the curve.

Parameters
Name Type Description

curve

CONST_OBJECT Profile.Curve

The curve to check.

Return values
Name Type Description

curveType

ENUM CurveType

The curve type.

Sample
curveType = Profile.Curve.getType(curve)
scale()
Short description

Scales a curve in the coordinate dimension and/or in the value dimension by recalculating curve parameters, centered around the origin. A nil value indicates unit scaling in the corresponding dimension.

Keywords

multiply, resize, transform

Parameters
Name Type Description

curve

CONST_OBJECT Profile.Curve

The source curve.

coordinateScale

FLOAT

Scale factor of coordinates.

valueScale

FLOAT

Scale factor of values.

Return values
Name Type Description

result

OBJECT Profile.Curve

Scaled curve.

Sample
local result = Profile.Curve.scale(curve, coordinateScale, valueScale)
scaleInplace()
Short description

In-place version of scale, see base function for full documentation.

Keywords

multiply, resize, transform

Parameters
Name Type Description

curve

OBJECT Profile.Curve

The curve to scale and the scaled curve.

coordinateScale

FLOAT

Scale factor of coordinates.

valueScale

FLOAT

Scale factor of values.

Return values
Name Type Description

result

OBJECT Profile.Curve

Reference to the scaled profile.

Sample
local result = Profile.Curve.scaleInplace(curve, coordinateScale, valueScale)
toProfile()
Short description

Evaluate the curve at all points in the reference profile and return as a new profile. The reference profile must have 1D sampling coordinates. For a smoother plot, extra samples may be inserted between the samples of the reference profile. This is controlled by the optional parameter extraSamples.

Parameters
Name Type Description

curve

CONST_OBJECT Profile.Curve

Input curve.

referenceProfile

CONST_OBJECT Profile

Reference profile.

extraSamples

INT

This many samples are inserted in the output profile between each two samples of the reference profile. Default is zero.

Return values
Name Type Description

curveProfile

OBJECT Profile

The sampled curve as a profile.

Sample
curveProfile = Profile.Curve.toProfile(curve, referenceProfile, extraSamples)
toString()
Short description

Get a human-readable string describing the curve.

Keywords

print, description

Parameters
Name Type Description

curve

CONST_OBJECT Profile.Curve

Input curve.

Return values
Name Type Description

str

STRING

String description of the curve.

Sample
print(Profile.Curve.toString(curve))
translate()
Short description

Translates a curve in the coordinate dimension and/or in the value dimension by recalculating curve parameters. A nil value indicates no translation in the corresponding dimension.

Keywords

move, shift, transform

Parameters
Name Type Description

curve

CONST_OBJECT Profile.Curve

The source curve.

coordinateTranslation

FLOAT

Translation of coordinates.

valueTranslation

FLOAT

Translation of values.

Return values
Name Type Description

result

OBJECT Profile.Curve

Translated curve.

Sample
local result = Profile.Curve.translate(curve, coordinateTranslation, valueTranslation)
translateInplace()
Short description

In-place version of translate, see base function for full documentation.

Keywords

move, shift, transform

Parameters
Name Type Description

curve

OBJECT Profile.Curve

The curve to translate and the translated curve.

coordinateTranslation

FLOAT

Translation of coordinates.

valueTranslation

FLOAT

Translation of values.

Return values
Name Type Description

result

OBJECT Profile.Curve

Reference to the translated profile.

Sample
local result = Profile.Curve.translateInplace(curve, coordinateTranslation, valueTranslation)

Profile.CurveFitter

Short description

For fitting parametric curves and functions to measurements stored in a profile object. Both ordinary least squares fitting (default) and robust fitting using RANSAC are possible.

Keywords

curve, function, least squares, ransac, trend, fitting

See also

Functions

create()
Short description

Create a curve fitter with default settings.

Return values
Name Type Description

curveFitter

HANDLE

Created curve fitter.

Sample
curveFitter = Profile.CurveFitter.create()
fitExponential()
Short description

Fit an exponential curve to the valid points in a profile.

Parameters
Name Type Description

curveFitter

HANDLE

Curve fitter to use.

inputProfile

OBJECT Profile

The profile to fit the curve to.

Return values
Name Type Description

expCurve

OBJECT Profile.Curve

The fitted exponential curve, or nil if fitting failed.

Sample
expCurve = Profile.CurveFitter.fitExponential(curveFitter, inputProfile)
fitGaussian()
Short description

Fit a Gaussian curve to the valid points in a profile. Fitting a Gaussian is quite sensitive to noise and degenerate cases, where the points do not come from a Gaussian function. Using RANSAC robust fitting is recommended as it is much less likely to fail.

Parameters
Name Type Description

curveFitter

HANDLE

Curve fitter to use.

inputProfile

OBJECT Profile

The profile to fit the curve to.

Return values
Name Type Description

gaussCurve

OBJECT Profile.Curve

The fitted Gaussian curve, or nil if fitting failed.

Sample
gaussCurve = Profile.CurveFitter.fitGaussian(curveFitter, inputProfile)
fitLine()
Short description

Fit a line to the valid points in a profile. Equivalent to fitting a first order polynomial. The coordinate system of the profile must be 1D.

Parameters
Name Type Description

curveFitter

HANDLE

Curve fitter to use.

inputProfile

OBJECT Profile

The profile to fit the curve to.

Return values
Name Type Description

line

OBJECT Profile.Curve

The fitted line.

Sample
line = Profile.CurveFitter.fitLine(curveFitter, inputProfile)
fitPolynomial()
Short description

Fit a polynomial curve to the valid points in a profile. Set the order parameter to zero for a constant function, one for a line, two for a quadratic function and so on. The coordinate system of the profile must be 1D.

Parameters
Name Type Description

curveFitter

HANDLE

Curve fitter to use.

inputProfile

OBJECT Profile

The profile to fit the curve to.

order

INT

Order of the polynomial to fit.

Return values
Name Type Description

polyCurve

OBJECT Profile.Curve

The fitted polynomial curve, or nil if fitting failed.

Sample
polyCurve = Profile.CurveFitter.fitPolynomial(curveFitter, inputProfile, order)
getPoints()
Short description

Get the edge points used in the last call to any of the fitting functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final curve. The second list contains all valid points in the profile not used for fitting the shape. For the least squares method, all points are always in the first list.

Parameters
Name Type Description

curveFitter

HANDLE

Curve fitter to use.

Return values
Name Type Description

inlierPoints

OBJECT Point

Points used for the final fitting of the curve, a subset of the valid points in the profile.

outlierPoints

OBJECT Point

Points not used for the final fitting, the remainder of the valid points.

Sample
inlierPoints, outlierPoints = Profile.CurveFitter.getPoints(curveFitter)
getResiduals()
Short description

Get fitting information from the last successful curve fit. Values are related to the inliers as can be obtained from getPoints.

Parameters
Name Type Description

curveFitter

HANDLE

Curve fitter to use.

Return values
Name Type Description

rmsError

FLOAT

The root mean squared error among the inliers.

inlierRatio

FLOAT

Ratio of inlier points to the total number of points, between 0 and 1.

inlierResiduals

FLOAT

Signed residuals for all inliers, the difference between the curve value and the profile value at each position.

outlierResiduals

FLOAT

Signed residuals for all outliers, the difference between the curve value and the profile value at each position.

Sample
rmsError, inlierRatio, inlierResiduals, outlierResiduals = Profile.CurveFitter.getResiduals(curveFitter)
setFitMode()
Short description

Set the fitting mode. The following modes are supported: - LEASTSQUARES uses all points. This is fast and easy, but can produce poor results if there are points that do not belong to the curve to be fitted (default). - RANSAC is a robust method with outlier rejection. Using this method, outlier points can be ignored. This mode requires an outlier margin to be set by setOutlierMargin. The number of iterations can be set by setIterations.

Keywords

ransac, robust, least squares

Parameters
Name Type Description

curveFitter

HANDLE

Curve fitter to use.

fitMode

ENUM Profile.CurveFitter.CurveFitMode

Fitting mode to use.

Sample
Profile.CurveFitter.setFitMode(curveFitter, fitMode)
setIterations()
Short description

Set the maximum number of iterations in the fitting step. A higher value makes the fitting more accurate, but consumes more computation time. The default is 1000 iterations.

Parameters
Name Type Description

curveFitter

HANDLE

Curve fitter to use.

iterations

INT

Number of iterations.

Sample
Profile.CurveFitter.setIterations(curveFitter, iterations)
setOutlierMargin()
Short description

Set the outlier margin when using RANSAC robust fitting mode. The interpretation of the margin parameter depends on the fitting mode parameter: - RANK: the outlier margin is interpreted as a rank measure, defining the rate of points to include. In this case, the margin must be in the range (0.0, 1.0). A rank margin of 0.7 means that only the best fitting 70% of all points will be included, and the rest ignored. - ABSOLUTE: the outlier margin is defined in absolute world units. Any points further away from the fitted curve than this margin will be ignored. In general a larger value means that more points are included in the fitting, which can improve the accuracy as long as all included points are valid. A smaller value makes the algorithm reject more points, which can increases robustness against single erroneous points. The default is an RANK margin of 0.5.

Parameters
Name Type Description

curveFitter

HANDLE

Curve fitter to use.

margin

FLOAT

Outlier margin, expressed in world coordinate units or as a rank measure, depending on the marginType.

marginType

ENUM Profile.CurveFitter.CurveOutlierMarginType

Outlier margin type.

Sample
Profile.CurveFitter.setOutlierMargin(curveFitter, margin, marginType)
toString()
Short description

Get a human-readable string describing the curve fitter.

Keywords

print, description

Parameters
Name Type Description

curve

CONST_OBJECT Profile.CurveFitter

Input curve fitter.

Return values
Name Type Description

str

STRING

String description of the curve.

Sample
print(Profile.CurveFitter.toString(curve))

Profile.Log

Short description

Object for incremental logging and statistics of measurements, typically in form of timeseries. Measurements are added one-by-one and statistical properties such as mean, standard deviation, min, max and histogram are updated incrementally. Thus, statistics over infinitely long timeseries can be recorded. There is an option to keep a vector of the most recently added values, for example for plotting reasons. There is also an option to maintain vectors of historic statistics (mean, min, max, std) over time intervals that is dynamically compressed (downsampled) when the vectors get full, so as to be able to calculate statistics over intervals in very long timeseries. Some properties are off by default, such as histogram updating and recent and historic value logging. These options need to be enabled explicitly using the dedicated functions for this, e.g., enableHistogram(). It is possible to save and load Profile.Log instances using the Object.save() and Object.load() functions.

Keywords

analytics, average, histogram, historic, incremental, infinite, logging, mean, record, standard deviation, std, time series, timeseries, statistics

Functions

addValue()
Short description

Add value(s). Values can be added one-by-one, in vector form to add several values at once, or in Profile form.

Parameters
Name Type Description

log

OBJECT [API:DataFormat:]

The log object.

value

CONST_AUTO

Value(s) to add. Can be a single float, a vector of floats, or a Profile object.

coordinate

CONST_AUTO

Optional coordinate of the added value(s), length and type must match the value input.

create()
Short description

Create new Log object

Return values
Name Type Description

log

OBJECT Profile.Log

The Log object.

enableHistogram()
Short description

Enables the histogram feature to incrementally maintain a histogram of all logged values.

Parameters
Name Type Description

log

OBJECT [API:DataFormat:]

The log object.

minValue

FLOAT

Center coordinate of the lowest bin.

maxValue

FLOAT

Center coordinate of the highest bin.

binsCount

INT

Number of bins.

enableHistoricStatistics()
Short description

Enables the historic statistics feature. Vectors of historic statistics (mean, max, min, std) over time periods are maintained. When the vectors gets full they are compressed (downsampled) a factor 2, and thus the time period represented also increases a factor 2. With this feature one can gather statistics over intervals in very long time series.

Parameters
Name Type Description

log

OBJECT [API:DataFormat:]

The log object.

periodCount

INT

Number of periods to keep. This is also the maximum size of the periods. Must be equal or larger than 10.

enableRecentValues()
Short description

Enables storage of recent values. The size of the vector to maintain needs to be specified.

Parameters
Name Type Description

log

OBJECT [API:DataFormat:]

The log object.

count

INT

The number of stored values.

getCount()
Short description

Get total number of values added to the log.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

count

INT

Number of added values.

getHistogram()
Short description

Get the histogram represented as a Profile object. The histogram feature must be enabled.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

recent

OBJECT Profile

Histogram with the frequency in the values and bin centers as coordinates.

getHistoricMax()
Short description

Get the maximum of the values in each historic period.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

max

OBJECT Profile

Profile with the maximum of the values in the periods.

getHistoricMean()
Short description

Get the mean of the values in each historic period.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

mean

OBJECT Profile

Profile with the mean of the values in the periods.

getHistoricMin()
Short description

Get the minimum of the values in each historic period.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

min

OBJECT Profile

Profile with the minimum of the values in the periods.

getHistoricPeriod()
Short description

Get number of values in each historic period.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

count

INT

Number of stored values per historic period.

getHistoricStdDev()
Short description

Get the standard deviation in each historic period.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

stddev

OBJECT Profile

Profile with the standard deviations of the values in the periods.

getMax()
Short description

Get the minimum value and its coordinate over all values added to the log.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

max

FLOAT

Maximum value.

coord

FLOAT

Coordinate of maximum value.

getMean()
Short description

Get the mean/average over all values added to the log.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

mean

FLOAT

Mean value.

getMin()
Short description

Get the minimum value and its coordinate over all values added to the log.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

min

FLOAT

Minimum value.

coord

FLOAT

Coordinate of minumum value.

getRecentValues()
Short description

Get the vector of recent values as a Profile object. Recent values must be enabled.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

recent

OBJECT Profile

Profile with the latest values and coordinates.

getStdDev()
Short description

Get the standard deviation over all values added to the log.

Parameters
Name Type Description

log

CONST_OBJECT [API:DataFormat:]

The log object.

Return values
Name Type Description

stddev

FLOAT

Standard deviation.

toString()
Short description

Get a string describing the log.

Keywords

print, description

Parameters
Name Type Description

curve

CONST_OBJECT Profile.Log

Input log.

Return values
Name Type Description

str

STRING

String description of the log.

Sample
print(Profile.Log.toString(curve))

Profile.Matching

Short description

Functions for matching and locating patterns in profiles based on different shape models such as sample pattern models.

Keywords

detection, feature, pattern, localization

Profile.Matching.PatternMatcher

Short description

Finds patterns in a profile based on template matching. Teach a pattern from a reference profile and call match to find the location of the same shape in a live profile.

Functions

create()
Short description

Creates a new matcher for 1D pattern localization in profiles.

Return values
Name Type Description

locator

HANDLE

The new instance.

Sample
locator = Profile.Matching.PatternMatcher.create()
getAllFoundMatches()
Short description

Get vector with all found matches sorted with descending score. A match is a local maximum in the comparison mode evaluation.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

Return values
Name Type Description

positions

FLOAT

Positions (indices) of found matches.

scores

FLOAT

scores.

Sample
 positions, scores = Profile.Matching.PatternMatcher.getAllFoundMatches(locator)
match()
Short description

Finds a pattern in a live profile by matching with the teach model. A teach call must be made first. The output is the position (index) of the best found match, with the origin for the template in the first element. Only one instance of a pattern is returned, the one with the strongest match score. However, after a match call, a vector of all match candidates can be obtained using the getAllFoundMatches function. A match score in the range [0.0, 1.0] is returned indicating the score strength. Depending on the comparison mode (selected in teach call), the score is calculated as follows: SAD: The best (lowest) SAD_min difference is found. The score is calculated as max(1.0 - SAD_min/(max_value - min_value), 0.0), where max value and min_value are the maximum and minimum values within the teach profile. This gives a score value that is 1.0 if the teach and live are identical, and 0.0 if for example all samples in the live profile deviates with at least the teach range. XCORRNORM: The best (highest) correlation coefficient XCORRNORM_max is found. The score is calculated as max(XCORRNORM_max, 0.0) to give as score 1.0 if the teach and match profiles correlate perfectly. Coordinate system handling: The coordinates are not considered in this function. Invalid flag usage: Invalid samples are excluded from the matching but can affect the score measure.

Keywords

locate, find

Parameters
Name Type Description

locator

HANDLE

The matcher instance to use.

liveProfile

CONST_OBJECT Profile

The live profile to find the shape in.

Return values
Name Type Description

position

FLOAT

Position (index) of the start of detected pattern in the live profile. Nil is returned if the match process failed.

matchScore

FLOAT

A score between 0.0 and 1.0 for the best detected pattern. High score means good match.

Sample
position, matchScore = Profile.Matching.PatternMatcher.match(locator, liveProfile)
setMaximumInvalidValues()
Short description

Set maximum number of invalid samples in the live profile, which overlaps the teach profile. Thus, matches where the teach profile overlaps with too many invalid samples in the live profile are discarded. The default value if this parameter is to allow any number of invalid values.

Parameters
Name Type Description

locator

HANDLE

The instance to use.

maxInvalidValues

INT

Maximum number of invalid samples.

Sample
 Profile.Matching.PatternMatcher.setMaximumInvalidValues(locator, maxInvalidValues)
teach()
Short description

Teaches a pattern model from a template profile. The template profile is typically shorter than the profile later used for matching in, e.g., it is a cropped version of a reference profile containing just the pattern of interest. Samples can be excluded from the teach model by setting the valid flags of the corresponding samples to invalid. Note that the teach profile must contain atleast 5 valid samples. There are two modes later used in the match call to determine how the teach pattern is compared to a profile to match in: SAD: Sum of absolute differences. A match score is calculated based on the sum of the absolute differences between the teach profile and the match profile. XCORRNORM: Cross correlation with normalization. A match score is calculated based on a cross-correlation operation. This mode is insensitive to different scalings and mean levels between the teach and match profiles.

Keywords

template, pattern

Parameters
Name Type Description

locator

HANDLE

The instance to use.

teachProfile

CONST_OBJECT Profile

The teach profile.

comparisonMode

ENUM ComparisonMode

Comparison method XCORRNORM or SAD. Default: XCORRNORM.

Return values
Name Type Description

success

BOOL

True if teach succeeded.

Sample
 success = Profile.Matching.PatternMatcher.teach(locator, teachProfile, matchMode)
toString()
Short description

Get a human-readable string describing the pattern matcher.

Keywords

print, description

Parameters
Name Type Description

locator

CONST_OBJECT Profile.Matching.PatternMatcher

Input pattern matcher.

Return values
Name Type Description

str

STRING

String description of the pattern matcher.

Sample
print(Profile.Matching.PatternMatcher.toString(patternMatcher))

Script

Short description

Provides general functions to communicate with the system and other Apps. E.g. functions to register script functions/-events to the system, in order to call them from other CROWNS. These functions are only available from scripting!

Functions

callFunction()
Short description

Call a CROWN function generically by name from a script context. This is useful if the function name is set dynamically and not known. This call blocks until the function has run and returns its return-values.

Parameters
Name Type Description

funcName

STRING

The function name of the function to call

param1

AUTO

First parameter for the function call (optional)

param2

AUTO

second parameter for the function call (optional)

param3

AUTO

third parameter for the function call (optional)

param4

AUTO

fourth parameter for the function call (optional)

param5

AUTO

fifth parameter for the function call (optional)

param6

AUTO

sixth parameter for the function call (optional)

param7

AUTO

seventh parameter for the function call (optional)

Return values
Name Type Description

success

BOOL

True if the function has been called successfully, false if function name was not a valid served function or wrong parameters passed to call the function.

result1

AUTO

First result of the function call (optional)

result2

AUTO

second result of the function call (optional)

result3

AUTO

third result of the function call (optional)

result4

AUTO

fourth result of the function call (optional)

result5

AUTO

fifth result of the function call (optional)

result6

AUTO

sixth result of the function call (optional)

result7

AUTO

seventh result of the function call (optional)

Sample
success, ret1, ret2 = Script.callFunction("theFuncName", param1, param2)
callFunctionAsync()
Short description

Call a CROWN function generically by name from a script context without waiting for the return value. This is useful if the function name is set dynamically and not known. This call does not block if the function is implemented in another thread/script and return-values are discarded. The call isn’t guaranteed to be run async: It depends on the implementation of the calling function.

Parameters
Name Type Description

funcName

STRING

The function name of the function to call

param1

AUTO

First parameter for the function call (optional)

param2

AUTO

second parameter for the function call (optional)

param3

AUTO

third parameter for the function call (optional)

param4

AUTO

fourth parameter for the function call (optional)

param5

AUTO

fifth parameter for the function call (optional)

param6

AUTO

sixth parameter for the function call (optional)

param7

AUTO

seventh parameter for the function call (optional)

Return values
Name Type Description

success

BOOL

True if the function has been called successfully, false if function name was not a valid served function

Sample
success = Script.callFunctionAsync("theFuncName", param1, param2)
deregister()
Short description

Deregisters a function from an event, which was registered at the event before. Deregistration are automatically done on script destruction.

Parameters
Name Type Description

eventName

STRING

The event name to deregister from.

consumer

STRING

The function name which was used for registering.

Return values
Name Type Description

success

BOOL

Returns true if successfully deregistered.

Sample
Script.deregister("Crown.Event","MyFunction")
disableGarbageCollectionByEngine()
Short description

Disables the automatic collectgarbage() calls by the engine for the current Lua script interpreter which are done after each script callback. Per default there is a full garbage collector run done on leaving the interpreter, to avoid non-deterministic behaviour due to no released CROWN objects from the interpreter. This disableGarbageCollectionByEngine()-function can be called at the beginning of a script in global scope to disable the automatic collectgarbage()-calls. If this function is used, the user has to know how lua garbage collection works and needs to take care by himself of the garbage collector settings of the Lua interpreter. The user also can manually release objects and handles using the function "Script.releaseObject". For easier usage of disabled engine garbage collection, this function also changes the garbagecollector settings to the following more aggressive settings: - collectgarbage("setpause", 100) — means "no pause". Lua default is 200 which is that the collection cycle starts only when the used memory is doubled. - collectgarbage("setstepmul", 400) — increases the work which each incremental step does. Lua default is 200. To tune the settings even more for your application, please read more about garbage collector in lua documentation. Basic suggestion: If the memory increases in your application and memory isn’t collected fast enough, increase the "setstepmul" to larger values than 400.

Sample
Script.disableGarbageCollectionByEngine()
isEventRegistered()
Short description

Returns true if a served event has minimum one registration active. Only works with events which were served by this script using the Script.serveEvent-function.

Parameters
Name Type Description

localEventName

STRING

Name of the event which is to be notified. The event needs to match the localEventName used in ServeEvent-function.

Return values
Name Type Description

success

BOOL

True if there is minimum one registration active.

registrationCount

INT

If there is a registration, this value contains the number of registrations, otherwise nil.

Sample
Script.isEventRegistered("MyEvent")
isServedAsEvent()
Short description

Returns true if the specified event name is served anywhere in the CROWN framework. This is especially useful when registering to dynamic events and checking before if the event is still served and available.

Parameters
Name Type Description

eventName

STRING

The event name which should be checked

Return values
Name Type Description

isServed

BOOL

True if the specified event name is currently served as CROWN event in the framework

isServedAsFunction()
Short description

Returns true if the specified function name is served anywhere in the CROWN framework. This is especially useful when calling dynamic functions and checking before if the function is still served and available.

Parameters
Name Type Description

funcName

STRING

The function name which should be checked

Return values
Name Type Description

isServed

BOOL

True if the specified function name is currently served as CROWN function in the framework

notifyEvent()
Short description

Use to notify an event which was served by the Script.serveEvent function by this app. Add any parameter to notify along with this event to the argument list.

Parameters
Name Type Description

localEventName

STRING

Name of the event which is to be notified. The event needs to match the localEventName used in ServeEvent-function.

parameters

AUTO

Parameters to notify.

Return values
Name Type Description

success

BOOL

True if successfully notified, false otherwise

Sample
Script.notifyEvent("MyEvent", value1, value2)
register()
Short description

Registers a function to an event. Registrations are possible only once per function and event. Further register calls for same combination return false. Registrations are always successfully done although the event might not be served already. In future the event still could get served and fired. If successfully registered there is a second return value added which indicates if the registered event is currently served by someone. This is useful to verify the wiring of an application. All calls to the registered function are executed sequentially in the context of the registering application. Execution of the event notifier is not blocked and event callback calls are queued up at the registered application. If there is a function pointer used for registering, the execution of the function always happens in the current script context (pay attention if registering another apps functions to use register function by name).

Parameters
Name Type Description

eventName

STRING

The event name to register to.

consumer

STRING

Name of the function to be called if the event occurs.

Return values
Name Type Description

success

BOOL

Returns true if successfully registered. False if the function is already registered on that event.

eventServed

BOOL

If registration was successful, this second parameter is added. True if the registered event is really served by someone.

Sample
Script.register("Crown.Event","MyFunction")
releaseObject()
Short description

Explicitly releases an object or handle from the script. If there is no one other holding a reference to the object, it is freed. This is useful if the user does not want to wait until the garbage collector releases it but does it at an explicit location.

Parameters
Name Type Description

objectToRelease

AUTO

The object(s) or handle(s) to release

Sample
Script.releaseObject(obj)
serveEvent()
Short description

Call to publish an event, so other apps can register on. The event must be specified in the app manifest over the AppStudio AppProperties Serves-tab.

Parameters
Name Type Description

crownEventName

STRING

The name used in the CROWN system. The app name must be prefixed to have a full qualified CROWN name (e.g. 'MyApp.MyEvent')

localEventName

STRING

Name of the event inside the lua script. Use this name for the Script.notifyEvent() function.

parameterListType

STRING

DEPRECATED! Not needed to be specified if the event is declared in the manifest over AppStudio AppProperties Serves-tab! Comma separated parameter definition list, e.g.: 'bool,string,int,object'. Types match the crown types. Syntax for one type: 'qualifier typename:multiplicity:alias'

Return values
Name Type Description

success

BOOL

True if successfully served, false otherwise

Sample
Script.serveEvent("MyApp.MyEvent", "MyEvent")
serveFunction()
Short description

Use to publish a lua function, so it can be called from other Apps. The function must be specified in the app manifest over the AppStudio AppProperties Serves-tab. All calls of the served function are executed sequentially in the context of the serving application. Execution of the caller is deferred until the function returns. There is no need for additional synchronization.

Parameters
Name Type Description

crownFunctionName

STRING

The name used in the CROWN system. The app name must be prefixed to have a full qualified CROWN name (e.g. 'MyApp.MyFunc')

localFunctionName

STRING

Name of the function inside the lua script, e.g. 'MyFunc'

parameterTypeList

STRING

DEPRECATED! Not needed to be specified if the function is declared in the manifest over AppStudio AppProperties Serves-tab! Comma separated parameter definition list, e.g.: 'bool,string,int,object'. Types match the crown types. Syntax for one type: 'qualifier typename:multiplicity:alias'

returnTypeList

STRING

DEPRECATED! Not needed to be specified if the function is declared in the manifest over AppStudio AppProperties Serves-tab! Comma separated return value definition list, e.g.: 'bool,string,int,object'. Types match the crown types. Syntax for one type: 'qualifier typename:multiplicity:alias'

Return values
Name Type Description

success

BOOL

True if successfully served, false otherwise

Sample
Script.serveFunction("MyApp.MyFunction", "MyFunction")
sleep()
Short description

Stops the execution of the interpreter at the given position and releases the processor. This can be used to delay the script at a given position. The usage of this function should be avoided for released applications but can be useful for testing. The script can be stopped also if it is sleeping at this position. During sleeping the lua script cannot handle events or other function calls. They are queued up and will be handled if the caller of this sleep returns from the script.

Parameters
Name Type Description

sleepTimeMs

INT

The time in milliseconds to sleep. The effective sleept time could be higher.

Sample
Script.sleep(50)
startScript()
Short description

Starts a new script with specified filename in a new interpreter, running in a new task context. This function is used to run several script tasks and interpreters inside a single app. One example where this is useful is if there are long-running blocking function calls, but the app should still stay responsive to events while these calls are executed. One way to realize this is is to use multiple apps, but using multiple scripts within one app has advantages: There is only one app that needs to be deployed, and the scripts within one app can share common lua code via require. The started scripts can use the CROWN framework to communicate with each other, the same way that communication between separate apps works: Via serving and using of functions and events. The script is started synchronous, so this function blocks until the main script scope of the newly started script has ran. After the main script scope has ran, the started script keeps active in the background and can react to events and functions calls to served functions. The lifetime of the script is bound to the app within it was started. Limitations: - The script file to be started must be located directly in the scripts/ directory of the app, it is not possible to start scripts which are located in a subdirectory. - It is not possible to debug a script that is started with this function in AppStudio directly. A possible workaround is to manually change the startScript() call for the specific script to be debugged to a require() to make it execute directly in the context of the main script of the app.

Parameters
Name Type Description

fileName

STRING

The file name of the Lua file which is to be started in a new interpreter. The file extension '.lua' can be omitted. The script file to be started must be located directly in the scripts/ directory of the app, it is not possible to start scripts which are located in a subdirectory.

priority

ENUM Priority

Priority of the task running the new interpreter. The available priority levels are the same as the levels that can be selected for an app in the app properties in AppStudio. The parameter is optional. By default, the priority of the script that calls the function is used. In case of the app main script, this is the app priority.

Return values
Name Type Description

success

BOOL

Returns true if the script file could be successfully loaded and started.

Sample
local success = Script.startScript("somescript.lua")

Script.Queue

Short description

Provides functionality to create new call queue. Per default each script has a one single default call queue to which all incoming calls are enqueued as they come in. Separate queues are useful to e.g. increase or decrease the queue priority or limit certain incoming events. The default queue of the script has priority 'MID'. All queues on the same priority are scheduled fair, which means each queue can process one queued call in each cycle. The handle to the queue needs to be held so that the queue stays active. If the handle is lost, the events are enqueued again in the default queue and currently queued events are lost. The limitation of queue sizes and discarding if full with the setMaxQueueSize and setDiscardIfFull functions is only possible, if the call is an event callback. For served function executions the limitation is not possible, because the functions always need to be executable and need a return value.

Functions

clear()
Short description

Clears all currently queued calls. This only works for event callbacks and not for function callbacks, because function calls always need a return value. Pay attention that directly during returning from this function there might be events already added again.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Sample
Script.Queue.clear(handle)
create()
Short description

Creates a new instance.

Return values
Name Type Description

handle

HANDLE

Handle to the new instance

Sample
-- Creates a new queue for the current running script with higher priority:
function myCallback()
end
queueHandle = Script.Queue.create()
queueHandle:setPriority("HIGH")
queueHandle:setFunction(myCallback)
-- Now register the callback at an event:
SomeProvider.register(provHandle, "OnSomeEvent", myCallback)
getSize()
Short description

Returns the current number of queue calls. Pay attention that directly during returning from this function there might be events already added again.

Parameters
Name Type Description

handle

HANDLE

The instance to use

Return values
Name Type Description

size

INT

The current queue size

Sample
size = Script.Queue.getSize(handle)
setDiscardIfFull()
Short description

Sets the behaviour for adding events to the queue if the queue is full. Per default the oldest element is discarded. To discard the newest to be added element, call this function with parameter true.

Parameters
Name Type Description

handle

HANDLE

The instance to use

bDiscardIfFull

BOOL

Set to true to discard the newest item which is currently added instead of discarding the oldest element

Sample
Script.Queue.setDiscardIfFull(handle, true)
setFunction()
Short description

Sets the function(s) which are handled by this queue. After this call, the specified functions are removed from the default script queue and added to this queue. So this call should be done as last call. This can be a lua function reference or local function name, and also be a served function name. To prioritize calls to a function served over Script.serveFunction, the served function name has to be used, and the function needs to be served before this call.

Parameters
Name Type Description

handle

HANDLE

The instance to use

function

STRING

The function or array of functions which should be handled by this queue.

Sample
Script.Queue.setFunction(handle, callbackFunc)
setMaxQueueSize()
Short description

Sets the maximum queue size of the call queue. This only works for event callbacks and not for function callbacks, because function calls always need a return value. Per default the queue is set to infinite size (=0). If the max queue size is reached, the oldest element is discarded per default. To change that behaviour use the setDiscardIfFull-Function.

Parameters
Name Type Description

handle

HANDLE

The instance to use

maxQueueSize

INT

The max number of events to queue. Per default 0 (=infinite)

Sample
Script.Queue.setMaxQueueSize(handle, 10)
setPriority()
Short description

Sets the relative priority of the queue compared to other queues of the script. Per default the priority MID is set, if this function is not called

Parameters
Name Type Description

handle

HANDLE

The instance to use

prio

ENUM Priority

The new priority to set

Sample
Script.Queue.setPriority(handle, "LOW")

SensorData

Short description

Provides access to additional sensor data information like origin and time stamp that is sent along with the actual measurement data.

Functions

getFrameNumber()
Short description

Returns the frame number (incremented by one for each measurement).

Parameters
Name Type Description

sensordata

CONST_OBJECT SensorData

Handle to the instance.

Return values
Name Type Description

frameno

INT

The frame number.

Sample
local frameNumber = SensorData.getFrameNumber(theSensorData)
getID()
Short description

Returns an application specific ID (e.g. object ID).

Parameters
Name Type Description

sensordata

CONST_OBJECT SensorData

Handle to the instance.

Return values
Name Type Description

id

INT

Returns the ID.

Sample
local id = SensorData.getID(theSensorData)
getMetaData()
Short description

Get the MetaData which is associated with the SensorData object. The MetaData object is optional and can contain dynamically configurable additional SensorData. The 'getMetaData' function returns an object of the type Container. The content can be accessed via the Container API.

Parameters
Name Type Description

sensordata

CONST_OBJECT SensorData

Input data to get the MetaData from.

Return values
Name Type Description

metadata

OBJECT Container

Optional MetaData object.

Sample
local metaData = SensorData.getMetaData(theSensorData)
getName()
Short description

Returns the component name of the corresponding data object (e.g. DepthImage or GreyImage).

Parameters
Name Type Description

sensordata

CONST_OBJECT SensorData

Handle to the instance.

Return values
Name Type Description

name

STRING

The component name of the corresponding data object.

Sample
local name = SensorData.getName(theSensorData)
getOrigin()
Short description

Returns the origin (e.g. device name).

Parameters
Name Type Description

sensordata

CONST_OBJECT SensorData

Handle to the instance.

Return values
Name Type Description

origin

STRING

Returns the data origin.

Sample
local origin = SensorData.getOrigin(theSensorData)
getTimestamp()
Short description

Returns the time stamp (in microseconds).

Parameters
Name Type Description

sensordata

CONST_OBJECT SensorData

Handle to the instance.

Return values
Name Type Description

timestamp

INT

The time stamp value (in microseconds).

Sample
local timeStamp = SensorData.getTimestamp(theSensorData)
toString()
Short description

Get a string representation of the SensorData.

Parameters
Name Type Description

sensordata

CONST_OBJECT SensorData

Input data to get the string representation.

Return values
Name Type Description

str

STRING

String representation of the SensorData

Sample
print("SensorData: " .. SensorData.toString(theSensorData))

SerialCom

Short description

Provides raw serial communication access. First a new SerialCom client needs to be created using the create function. Afterwards the baudrate and the other settings need to be done. Then a call to the open-function opens the serial port and transmit calls and OnReceive events are possible. Data could be transmitted to the server using the "transmit" function. Data could be received by a register to the "OnReceive" event or by calling the blocking receive()-function. The transmitted and received data is raw data. It could get automatically framed for transmitting and receiving can be automatically parsed if setting a framing with the "setFraming" function. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.

Functions

close()
Short description

Closes the serial handle.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

Sample
SerialCom.close(handle)
create()
Short description

Creates a serial communication interface instance if port exists and not already in use.

Parameters
Name Type Description

portName

ENUM SerialPorts

The (device dependent) name of the serial port which should be opened.

Return values
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create(). Nil if not available or already in use.

Sample
handle = SerialCom.create("SER1")
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

isOpened()
Short description

Determine whether the serial port is open or not.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

Return values
Name Type Description

isOpen

BOOL

true if the COM port is open, false if not

Sample
isOpen = SerialCom.isOpened(handle)
open()
Short description

Opens the serial connection that has been configured with the set* functions.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

Return values
Name Type Description

isOpen

BOOL

Returns true if interface could be opened. If false, the port might be in use already.

Sample
success = SerialCom.open(handle)
receive()
Short description

Receives data from the client with a specified timeout. If timeout is zero then it directly returns. The data could be framed if the "setFraming" function was called before. Incoming data between multiple receive calls is queued per message. There is a fix receive queue size of 10 packets per default and can be changed using the setReceiveQueueSize()-function. More data is discarded.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

timeout

INT

Timeout in ms to wait for received data. 0 is default and means directly return.

Return values
Name Type Description

data

BINARY

The data which was received

Sample
data = SerialCom.receive(handle, 5000)
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

setBaudRate()
Short description

Sets the baudrate. Default is '57600'.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

baudRate

INT

One of 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200

Sample
SerialCom.setBaudRate(handle, 9600)
setDataBits()
Short description

Sets the number of data bits. Default is '8'.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

dataBits

INT

8 or 7

Sample
SerialCom.setDataBits(handle, 8)
setFlowControl()
Short description

Enables or disables hardware flow control. Default is 'false'.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

enabled

BOOL

true to enable flow control, false to disable

Sample
SerialCom.setFlowControl(handle, false)
setFraming()
Short description

Sets the framing which is to be used. If not set the default framing is no framing (raw byte/packet-wise connection). Framing could be also explicitly disabled by calling this function with 2 empty binary data for rx and tx. One framing part could be maximum size of 9 bytes. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded. The close and open functions has to be called afterwards so that the setting gets active.

Parameters
Name Type Description

handle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

rxStart

BINARY

Start framing for receiving, could be empty string. Maximum size of 9.

rxStop

BINARY

Stop framing for receiving. If empty then all raw data is received. Maximum size of 9.

txStart

BINARY

Start framing for sending, could be empty string. Maximum size of 9.

txStop

BINARY

Stop framing for sending, could be empty string. Maximum size of 9.

Sample
SerialCom.setFraming(handle, "", "", "", "")
setFramingBufferSize()
Short description

Sets the size of the internal framing parser buffer which is used if there is a rx or tx framing set using the setFraming function. If the rx or tx framing isn’t set, its buffer size has no effect. This size is the maximum size of a packet which can be parsed by the framing. The size is used for start and stop framing. Default is 10240 bytes. The close and open functions have to be called afterwards for activating the setting.

Parameters
Name Type Description

handle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

rxBufSize

INT

The new framing buffer size for framed receiving.

txBufSize

INT

The new framing buffer size for framed transmitting.

Sample
SerialCom.setFramingBufferSize(handle, 21000, 21000)
setHandshake()
Short description

Enables or disables handshake. Default is 'false'.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

enabled

BOOL

true to enable Xon/Xoff handshake, false to disable

Sample
SerialCom.setHandshake(handle, true)
setParity()
Short description

Sets the parity. Default is 'N'.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

parity

CHAR

One of "N", "O", "E", "M", "S" (None, Odd, Even, Mark, Space)

Sample
SerialCom.setParity(handle, "N")
setReceiveQueueSize()
Short description

Sets the internal queue size for the receive()-function. Default is 10 packets and discarding the oldest item and warn if overrun occurs. Set to 0 to disable the queue and receiving from the receive()-function, which also increases performance if only receiving over OnReceive-event.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the UDP socket

queueSize

INT

The new receive queue size.

bDiscardIfFull

BOOL

Set to true to discard the newest item which is currently added instead of discarding the oldest element. Default is false.

warnOverruns

BOOL

Set to false to disable warning on overruns when using the receive()-function. Default is true.

Sample
SerialCom.setReceiveQueueSize(handle, 50)
setStopBits()
Short description

Sets the number of stop bits. Default is '1'.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

stopBits

INT

1 or 2

Sample
SerialCom.setStopBits(handle, 1)
setTermination()
Short description

Enables the internal termination of the serial interface. Default is 'false'.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

terminated

BOOL

true to enable internal termination, false to disable

Sample
SerialCom.setTermination(handle, true)
setType()
Short description

Selects the type of the serial interface. Default is 'RS232'.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

type

ENUM SerialComTypes

Interface type which is available on the device. E.g. 'RS232', 'RS422', 'RS485'

Sample
SerialCom.setType(handle, "RS232")
transmit()
Short description

Transmits the data on the serial handle. If framing is set using the "setFraming" function, then the framing characters are automatically prefixed and suffixed to the transmitted data. Blocks until data has been transmitted.

Parameters
Name Type Description

ifHandle

HANDLE

Handle to the Serial Communication Interface that has been returned by SerialCom.create().

data

BINARY

The data which should be sent

Return values
Name Type Description

numberOfBytesTransmitted

INT

Number of bytes transmitted; 0 if transmit failed

Sample
SerialCom.transmit(handle, "data to transmit")

Events

OnReceive
Short description

The on receive event which is thrown for every new received data.

Parameters
Name Type Description

handle

HANDLE

This is a handle event and must be registered on the handle

data

BINARY

The received data

Shape

Short description

A 2D geometric primitive. A Shape can be one of the geometric types Line, LineSegment, Polyline, Rectangle, Circle, Ellipse, Arc or Sector. The Shape object is represented in mathematical analytical form. Operations such as finding intersection points, distances and transforming the Shape are for this reason efficiently computed. Note when used in context of images: The Shapes are defined in the image world coordinate system, i.e., in world scale (typically millimeters) and not in pixel coordinates. The image world coordinate system is left handed, with the x-axis pointing rightwards and the y-axis pointing downwards, and the origin centered at the upper left pixel. In this coordinate system, positive translations along the y-axis will shift the shape downwards, and positive rotations are clockwise. Thus, this is different compared to usage in a right-handed coordinate system context.

Functions

appendPoint()
Short description

Append a point to a polyline shape.

Parameters
Name Type Description

shape

OBJECT Shape

The shape to modify. Must be a polyline shape.

point

CONST_OBJECT Point

2D point to add.

Sample
Shape.appendPoint(polyline, Point.create(x, y))
clone()
Short description

Create an independent copy of this shape. If the input is a vector of shapes, the output is a vector of shapes.

Parameters
Name Type Description

inputShape

CONST_OBJECT Shape

The shape to clone.

Return values
Name Type Description

outputShape

OBJECT Shape

The new copy.

Sample
outputShape = Shape.clone(inputShape)
contains()
Short description

Check if the input point is contained within the enclosed area of the given shape. Always returns false if the shape is not closed. If more than one shape is provided true is returned if the point is inside any of the shapes. If more than one point is provided a vector is returned with one value for each input point.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Closed shape enclosing an area

point

CONST_OBJECT Point

Point (2D) to check if contained within the area

Return values
Name Type Description

isInside

BOOL

True if the point is contained within the enclosed area, false if not

Sample
isInside = Shape.contains(shape, point)
createArc()
Short description

Create an arc shape (part of a circle). Radius and deltaAngle must be non-negative. By providing vectors of centers, radii, angles and delta angle several arcs can be created. All vectors must be of equal length.

Parameters
Name Type Description

center

CONST_OBJECT Point

Center point (2D) of the arc. Can also be a vector of center points to create several arcs.

radius

FLOAT

Arc radius. Can also be a vector of radii to create several arcs.

angle

FLOAT

Angle where the arc starts, in radians. Can also be a vector of angles to create several arcs.

deltaAngle

FLOAT

The angular length of the arc, in radians. Can also be a vector of delta angles to create several sectarcsors.

Return values
Name Type Description

arc

OBJECT Shape

The created arc, or vector of arcs for for vector input.

Sample
arc = Shape.createArc(centerPoint, radius, angle, deltaAngle)
createCircle()
Short description

Create circle shape(s). By providing vectors of centers and radii, several circles can be created. All vectors must be of equal length.

Parameters
Name Type Description

center

CONST_OBJECT Point

A single 2D Point or a vector of points. If the input is a vector, a vector of circles is created.

radius

FLOAT

Circle radius. Must be non-negative. Can also be a vector to create several circles.

Return values
Name Type Description

circle

OBJECT Shape

The created circle or vector of circles.

Sample
circle = Shape.createCircle(centerPoint, radius)
createEllipse()
Short description

Create an ellipse shape. Radii must be non-negative. By providing vectors of centers, radiusX, radiusY and rotation, several ellipses can be created. All vectors must be of equal length.

Parameters
Name Type Description

center

CONST_OBJECT Point

Center point (2D). Can also be a vector of centre points to create several ellipses.

radiusX

FLOAT

Radius along the x axis (before rotation). Can also be a vector of radii to create several ellipses.

radiusY

FLOAT

Radius along the y axis (before rotation). Can also be a vector of radii to create several ellipses.

rotation

FLOAT

Ellipse rotation in radians. Can also be a vector of rotations to create several ellipses. A positive rotation rotates the x-axis towards the y-axis. Note that when used as region for an image, the image has a left-hand system with the y-axis pointing downwards, in which a positive rotation means a clockwise direction.

Return values
Name Type Description

ellipse

OBJECT Shape

The created ellipse, or vector of ellipses for for vector input.

Sample
ellipse = Shape.createEllipse(centerPoint, radiusX, radiusY, rotation)
createLine()
Short description

Create an infinite line shape that connects (and extends beyond) two given points. The points must not be the same. By providing vectors of end-points, several infinite lines can be created. The vectors must be of equal length.

Parameters
Name Type Description

point1

CONST_OBJECT Point

A point (2D) on the line. Can also be a vector of points to create several lines.

point2

CONST_OBJECT Point

Another point (2D) on the line. Can also be a vector of points to create several lines.

Return values
Name Type Description

line

OBJECT Shape

The created line, or vector of lines for for vector input.

Sample
line = Shape.createLine(point1, point2)
createLineSegment()
Short description

Create a finite length line segment between two given endpoints. By providing vectors of end-points, several line segments can be created.

Parameters
Name Type Description

point1

CONST_OBJECT Point

First endpoint (2D) of the line segment. Can also be a vector of points to create several line segments.

point2

CONST_OBJECT Point

Second endpoint (2D) of the line segment. For vector input the length of the vector must match the vector containing the first endpoints

Return values
Name Type Description

lineSegment

OBJECT Shape

The created line segment, or vector of line segments for for vector input.

Sample
lineSegment = Shape.createLineSegment(point1, point2)
createPolyline()
Short description

Create a polyline shape (sequence of line segments connected to an open contour or closed polygon).

Parameters
Name Type Description

points

CONST_OBJECT Point

List of points (2D) to connect to a polyline

closed

BOOL

If true, the first and last points are connected to form a closed polygon. Otherwise it becomes an open contour.

Return values
Name Type Description

polyline

OBJECT Shape

The created polyline or polygon shape

Sample
polyline = Shape.createPolyline(points, true)
createRectangle()
Short description

Create a rectangle shape. Width and height must be non-negative. By providing vectors of centers, width, height and rotation, several rectangles can be created. All vectors must be of equal length.

Parameters
Name Type Description

center

CONST_OBJECT Point

Center point (2D) of the rectangle. Can also be a vector of center points to create several rectangles.

width

FLOAT

Rectangle width (size along the x axis before rotation). Can also be a vector of center points to create several rectangles.

height

FLOAT

Rectangle height (size along the y axis before rotation). Can also be a vector of heights to create several rectangles.

rotation

FLOAT

Optional rectangle rotation in radians, default is zero. A positive rotation rotates the x-axis towards the y-axis. Note that when used as region for an image, the image has a left-hand system with the y-axis pointing downwards, in which a positive rotation means a clockwise direction. Can also be a vector of rotations to create several rectangles.

Return values
Name Type Description

rectangle

OBJECT Shape

The created rectangle shape, or vector of rectangles for for vector input.

Sample
rectangle = Shape.createRectangle(center, width, height, rotation)
createSector()
Short description

Create a circular sector defining a region contained within two angles, an inner and an outer radius. Radii and deltaAngle must be non-negative, outerRadius must be larger than innerRadius. By providing vectors of centers, innerRadius, outerRadius, angle and deltaAngle several sectors can be created. All vectors must be of equal length.

Parameters
Name Type Description

center

CONST_OBJECT Point

Center point of the circle from which the sector is defined. Can also be a vector of center points to create several sectors.

innerRadius

FLOAT

Inner radius of the sector. Can also be a vector of inner radii to create several sectors.

outerRadius

FLOAT

Outer radius of the sector. Can also be a vector of outer radii to create several sectors.

angle

FLOAT

Angle where the sector starts, in radians. Can also be a vector of angles to create several sectors.

deltaAngle

FLOAT

The angular length of the sector, in radians. Can also be a vector of delta angles to create several sectors.

Return values
Name Type Description

sector

OBJECT Shape

The created sector, or vector of sectors for for vector input.

Sample
sector = Shape.createSector(center, innerRadius, outerRadius, angle, deltaAngle)
cropLine()
Short description

Returns the part of a line within a rectangle as a new line segment. If the line does not intersect the rectangle, nil is returned. Several lines in a vector can be cropped at once, in which case all lines must be within the box for the call to succeed.

Parameters
Name Type Description

line

CONST_OBJECT Shape

The line shape to be cropped, or a vector of lines to be cropped.

rectangle

CONST_OBJECT Shape

The rectangle to keep the line within.

Return values
Name Type Description

line

OBJECT Shape

The part of the line within the rectangle as a line segment, or a vector of line segments. Nil is returned if any line is outside the box.

Sample
lineSegment = Shape.cropLine(line, rectangle)
getArcParameters()
Short description

Get the parameters defining the arc. Can only be called for arc shapes (returns nil otherwise). A vector of arc shapes can be provided, in which case vectors of parameters are returned.

Parameters
Name Type Description

arc

CONST_OBJECT Shape

Input arc shape or vector of arc shapes.

Return values
Name Type Description

center

OBJECT Point

Center point of the circle from which the arc is defined, or vector of center points for vector input.

radius

FLOAT

Radius of the arc, or vector of radii for vector input.

angleRad

FLOAT

Angle where the arc starts, in radians, or vector of angles for vector input.

deltaAngleRad

FLOAT

The angular length of the arc, in radians, or vector of angular lengths for vector input.

Sample
center, radius, angleRad, deltaAngleRad = Shape.getArcParameters(arc)
getArea()
Short description

Get the area of the region enclosed by a 2D Shape. A vector of shapes can be provided, in which case a vector of areas is returned.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or vector of shapes.

Return values
Name Type Description

area

FLOAT

Area of shape, or vector of areas for vector input.

Sample
area = Shape.getArea(shape)
getBoundingBox()
Short description

Get a rectangular axis-aligned bounding box of the shape (minimum box that contains the shape). The returned box is another Shape object. To get the actual bounds as float values, call getBounds.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or shapes

Return values
Name Type Description

boundingBox

OBJECT Shape

Axis-aligned bounding box as a rectangle shape, or vector for vector input.

Sample
boundingBox = Shape.getBoundingBox(shape)
getBoundingBoxOriented()
Short description

Gets a rectangular rotated bounding box of the given shape. This is the minimum area rectangle that still contains the shape. The return box is another Shape object.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or shapes.

Return values
Name Type Description

minimumAreaRectangle

OBJECT Shape

The oriented minimum area bounding box, or vector for vector input.

Sample
minimumAreaRectangle = Shape.getBoundingBoxOriented(shape)
getBounds()
Short description

Get the bounds of the shape as float values. Fails for invalid and unbounded shapes.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape

Return values
Name Type Description

xMin

FLOAT

Minimum x coordinate

yMin

FLOAT

Minimum y coordinate

xMax

FLOAT

Maximum x coordinate

yMax

FLOAT

Maximum y coordinate

Sample
xMin, yMin, xMax, yMax = Shape.getBounds(shape)
getCenterOfGravity()
Short description

Get the center of gravity of the region enclosed within the shape for closed shapes. For open shapes, the center of gravity of the contour is returned. Returns nil for infinite or invalid shapes.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or vector of shapes.

Return values
Name Type Description

centerOfGravity

OBJECT Point

Center of gravity as a 2D Point, or vector of points for vector input.

Sample
point = Shape.getCenterOfGravity(shape)
getCircleParameters()
Short description

Get the parameters defining the circle. Can only be called for circle shapes (returns nil otherwise). A vector of circle shapes can be provided, in which case vectors of parameters are returned.

Parameters
Name Type Description

circle

CONST_OBJECT Shape

Input circle shape or vector of circle shapes.

Return values
Name Type Description

center

OBJECT Point

Center point of the circle, or vector of center points for vector input.

radius

FLOAT

Radius of the circle, or vector of radii for vector input.

Sample
center, radius = Shape.getCircleParameters(circle)
getClosestContourPoint()
Short description

Get the closest point on a shape contour to a given external point. Fails if the point is not a 2D point. If there are more than one shape provided the closest point on any shape countour is returned. If there are more than one point provided one point is returned for each input point.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Shape to process.

point

CONST_OBJECT Point

Point to process.

Return values
Name Type Description

closestPoint

OBJECT Point

Closest point on any of the shapes.

distance

FLOAT

The distance to the closest point.

Sample
closestPoint = Shape.getClosestContourPoint(shape, point)
getCompactness()
Short description

Gets a measure of how compact a shape is, as a number between 0.0 and 1.0. A circle has compactness 1.0. The measure is calculated as (4*pi*Area)/perimeter^2. Degenerate shapes has compactness zero.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or vector of shapes.

Return values
Name Type Description

compactness

FLOAT

Compactness of a shape, or vector for vector input.

Sample
compactness = Shape.getCompactness(shape)
getContourPoints()
Short description

Get the points defining the shape contour. Only supported for shapes consisting of a finite number of points (line segments, rectangles and polylines). To get a polygon approximation of a circle or ellipse, use toPolyline.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Shape to process

Return values
Name Type Description

points

OBJECT Point

List of points (2D) that approximates or represents the input shape.

Sample
points = Shape.getContourPoints(shape)
getConvexHull()
Short description

Gets the convex hull of a given shape. Currently fails if the shape is something other than a polyline. Convert general shapes to polylines using Shape.toPolyline.

See also

Shape.toPolyline

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Shape or shapes to process.

Return values
Name Type Description

hull

OBJECT Shape

Resulting convex hull as a polyline, or vector for vector input.

Sample
hull = Shape.getConvexHull(shape)
getConvexity()
Short description

Returns a measure of how convex a given shape is, as a number between 0.0 and 1.0. It is given as a quotient between the area of the shape and its convex hull. A convex object has convexity 1.0. All open shapes such as lines, arcs and open polylines return 0.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or vector of shapes.

Return values
Name Type Description

convexity

FLOAT

A measure of how convex the shape is, or vector of measurements for vector input.

Sample
convexity = Shape.getConvexity(shape)
getEllipseParameters()
Short description

Get the parameters defining the ellipse. Can only be called for ellipse shapes (returns nil otherwise). A vector of ellipse shapes can be provided, in which case vectors of parameters are returned.

Parameters
Name Type Description

ellipse

CONST_OBJECT Shape

Input ellipse shape or vector of ellipse shapes.

Return values
Name Type Description

center

OBJECT Point

Center point (2D), or vector of center points for vector input.

radiusX

FLOAT

Radius along the x axis (before rotation), or vector of radii for vector input.

radiusY

FLOAT

Radius along the y axis (before rotation), or vector of radii for vector input.

rotationRad

FLOAT

Ellipse rotation, in radians. Vector of rotations for vector input.

Sample
center, radiusX, radiusY, rotationRad = Shape.getEllipseParameters(ellipse)
getElongation()
Short description

Get the a measure of elongation of a shape. It is calculated as lengthAlongMajorAxis/lengthAlongMinorAxis and is therefore a number between 1.0 (e.g., a circle) and infinity (e.g., a line). For some shapes, i.e, Polyline, Arc and Sector, the elongation of the shape bounding box is returned.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or vector of shapes.

Return values
Name Type Description

elongation

FLOAT

Elongation, or vector of elongations for vector input.

Sample
elongation = Shape.getElongation(shape)
getIntersectionAngle()
Short description

Get angle of the intersection between two lines or line segments. If the line segments do not intersect the lines are extrapolated to calculate the intersection angle.

Parameters
Name Type Description

line1

CONST_OBJECT Shape

First shape. Must be a line or line segment.

line2

CONST_OBJECT Shape

Second shape. Must be a line or line segment.

Return values
Name Type Description

angle

FLOAT

Intersection angle, in radians.

Sample
angle = Shape.getIntersectionAngle(line1, line2)
getIntersectionPoints()
Short description

Get points on the intersection between two shape contours.

Parameters
Name Type Description

shape1

CONST_OBJECT Shape

First shape to intersect.

shape2

CONST_OBJECT Shape

Second shape to intersect.

Return values
Name Type Description

points

OBJECT Point

List of intersection points.

Sample
points = Shape.getIntersectionPoints(shape1, shape2)
getLineDistance()
Short description

Returns the minimum and maximum distance from all points on the shape to the reference line. Distances are measured orthogonal to the reference line. The query shape should have finite size.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

The shape or shapes to check distance to.

referenceLine

CONST_OBJECT Shape

The reference line.

Return values
Name Type Description

minDist

FLOAT

The orthogonal distance from the line to the closest point on the shape, or nil if projection failed. Vector with distances for vector input.

maxDist

FLOAT

The orthogonal distance from the line to the point on the shape furthest away from the line, or nil if projection failed. Vector with distances for vector input.

Sample
minDist, maxDist = Shape.getLineDistance(shape, referenceLine)
getLineParameters()
Short description

Get the parameters defining the line or line segment. Can only be called for line or line segment shapes (returns nil otherwise). For line segments, the two endpoints are returned. For lines, the first point used to define the line is returned, the second point is one unit distance away from the first point along the line. A vector of line or line segment shapes can be provided, in which case two vectors of parameters are returned.

Parameters
Name Type Description

line

CONST_OBJECT Shape

Input line or line segment shape or vector of line or line segment shapes.

Return values
Name Type Description

point1

OBJECT Point

First line segment endpoint or one point on the line, or vector of points for vector input.

point2

OBJECT Point

Second line segment endpoint or another point on the line, or vector of points for vector input.

Sample
point1, point2 = Shape.getLineParameters(line)
getPerimeterLength()
Short description

Get the length of the perimeter of a shape.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or vector of shapes.

Return values
Name Type Description

perimeterLength

FLOAT

Perimeter length, or vector of lengths for vector input.

Sample
perimeterLength = Shape.getPerimeterLength(shape)
getPolylineParameters()
Short description

Get the points defining the polyline and a flag indicating if the polyline is closed.

Parameters
Name Type Description

polyline

CONST_OBJECT Shape

The polyline.

Return values
Name Type Description

points

OBJECT Point

Vertices for the polyline.

closed

BOOL

If true, the first and last points are connected to form a closed polygon. Otherwise it is an open contour.

Sample
points, closed = Shape.getPolylineParameters(polyline)
getRadius()
Short description

Get the radius of the shape. This function is deprecated. Use specific functions for getting the parameters of each Shape instead, for example Shape.getCircleParameters, or the bounding box functions.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape

Return values
Name Type Description

radius

FLOAT

Radius of circumscribed circle

Sample
radius = Shape.getRadius(shape)
getRectangleParameters()
Short description

Get the parameters defining the rectangle. Can only be called for rectangle shapes (returns nil otherwise). A vector of rectangle shapes can be provided, in which case three vectors of parameters are returned.

Parameters
Name Type Description

rectangle

CONST_OBJECT Shape

Input rectangle shape or vector of rectangle shapes.

Return values
Name Type Description

center

CONST_OBJECT Point

Center point (2D) of the rectangle, or vector of center points for vector input.

width

FLOAT

Rectangle width (size along the x axis before rotation), or vector of widths for vector input.

height

FLOAT

Rectangle height (size along the y axis before rotation), or vector of heights for vector input.

rotation

FLOAT

Rectangle rotation in radians. Counter-clockwise rotation in an x/y coordinate system. Vector of rotations for vector input.

Sample
center, width, height, rotationRad = Shape.getRectangleParameters(rectangle)
getSectorParameters()
Short description

Get the parameters defining the sector. Can only be called for sector shapes (returns nil otherwise). A vector of sector shapes can be provided, in which case vectors of parameters are returned.

Parameters
Name Type Description

sector

CONST_OBJECT Shape

Input sector shape or vector of sector shapes.

Return values
Name Type Description

center

OBJECT Point

Center point of the circle from which the sector is defined, or vector of center points for vector input.

innerRadius

FLOAT

Inner radius of the sector, or vector of inner radii for vector input.

outerRadius

FLOAT

Outer radius of the sector, or vector of outer radii for vector input.

angleRad

FLOAT

Angle where the sector starts, in radians, or vector of angles for vector input.

deltaAngleRad

FLOAT

The angular length of the sector, in radians. Vector of angular lengths for vector input.

Sample
center, innerRadius, outerRadius, angleRad, deltaAngleRad = Shape.getSectorParameters(sector)
getType()
Short description

Return the geometric type the Shape represents.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

The shape or shapes to check.

Return values
Name Type Description

shapeType

ENUM ShapeType

The shape type or vector with shape types.

Sample
shapeType = Shape.getType(shape)
isClosed()
Short description

Check if this is a closed shape. A contour is closed if it has no endpoints and encloses an area. For example, a circle is closed while a line segment is not.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

The shape or shapes to check

Return values
Name Type Description

isClosed

BOOL

True if the shape is closed, otherwise false

Sample
isClosed = Shape.isClosed(shape)
rotate()
Short description

Rotate the shape. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For arcs and sectors, the nominal center is the center of the base circle. Note on rotation direction: When a shape is used for defining a region in an image, it is interpreted in the left handed coordinate system of the image. In a left-handed system, a positive rotation is in the clockwise direction.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or shapes.

rotationAngle

FLOAT

The rotation angle in radians

rotationCenter

CONST_OBJECT Point

The rotation center. The nominal center of the shape is used if unspecified.

Return values
Name Type Description

outputShape

OBJECT Shape

The rotated shape or shapes, or nil if the input shape is invalid.

Sample
outputShape = Shape.rotate(shape, rotationAngle, rotationCenter)
toImage()
Short description

Convert the shape into an image, setting pixels within the shape contour to a specific value. The value is in world coordinates and is cropped to the representable range. Pixels outside are set to pixel value zero. Only closed shapes are supported. If several shapes are given, they are all drawn in the same image. Invalid shapes in a list of shapes are ignored.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or vector of shapes.

referenceImage

CONST_OBJECT Image

Reference image, used to define pixel-world mapping.

worldValue

FLOAT

World value to use within the region. Default is 255.

Return values
Name Type Description

outputImage

OBJECT Image

Resulting image displaying the shape or nil if not supported.

Sample
outputImage = Shape.toImage(shape,refImage,worldValue)
toLine()
Short description

Convert a line segment or a vector of line segments to infinite lines. Only supports line segment input.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Line segment or vector of line segments to convert.

Return values
Name Type Description

line

OBJECT Shape

Line or vector of lines created by extending the line segment end points to infinity.

Sample
line = Shape.toLine(lineSegment)
toPixelRegion()
Short description

Rasterize a Shape object into a PixelRegion object, using a reference image to define the pixel-world mapping. A vector of shape objects generates a vector of PixelRegion objects.

Keywords

draw, render, rasterize

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or shapes.

referenceImage

CONST_OBJECT Image

Reference image, used to define pixel-world mapping.

fill

BOOL

Set to true to generate a filled region, false to generate a border region. Non-closed shapes will always generate a border only. Default: true.

Return values
Name Type Description

pixelRegion

OBJECT Image.PixelRegion

Pixel region representation of the shape, or a vector of pixel region representations of the shapes.

Sample
pixelRegion = Shape.toPixelRegion(shape, referenceImage)
toPolyline()
Short description

Convert this shape to a polyline shape, approximating the true shape if needed (if the true shape is a circle, ellipse or arc). For a shape that is already a polyline, this function can be used to approximate it with a less detailed polyline.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Shape to convert, or vector of shapes.

epsilon

FLOAT

Maximum approximation error in the polyline approximation.

maxPoints

INT

Maximum number of points to use in the approximation (default is 1000). This is a stronger requirement than the epsilon and puts a limit on the function memory usage.

Return values
Name Type Description

polylineShape

OBJECT Shape

The shape represented as a polyline, or vector of polylines.

Sample
polylineShape = Shape.toPolyline(shape, epsilon)
toShape3D()
Short description

Convert a 2D Shape into the corresponding 3D shape. An optional rigid Transform object may be provided. Without transform, the 3D shape is created in the z=0 plane. The transform is applied after creation, allowing 3D Shapes in other planes. Nil is returned if the input contains invalid shapes or shapes without a corresponding 3D shape.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or vector of shapes.

transform

CONST_OBJECT Transform

Optional transform from the z=0 plane to the desired plane. Must be rigid or less general.

Return values
Name Type Description

outputShape

OBJECT Shape3D

The corresponding Shape3D or nil if not supported, or vector of 3D shapes.

Sample
outputShape = Shape.toShape3D(shape, transform)
toString()
Short description

Get a human-readable string describing the shape.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape

Return values
Name Type Description

str

STRING

String description of the shape

Sample
print(Shape.toString(shape))
transform()
Short description

Transform a shape or a vector of shapes. Fails if the transform is not a 2D transform or if the transform would change the underlying shape type.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or shapes.

transform

CONST_OBJECT Transform

Transform to apply.

Return values
Name Type Description

outputShape

OBJECT Shape

Transformed shape or shapes, or nil on error.

Sample
outputShape = Shape.transform(shape, transform)
translate()
Short description

Translate the shape, i.e., shift it along the x,y-axes. Note on translation direction: When a shape is used for defining a region in an image, it is interpreted in the left handed coordinate system of the image in which the y-axis is pointing downwards. A positive translation therefore shifts the shape downwards when overlaid on top of the image.

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input shape or shapes

translationX

FLOAT

The translation along the X-axis

translationY

FLOAT

The translation along the Y-axis

Return values
Name Type Description

outputShape

OBJECT Shape

The translated shape or shapes, or nil if the input shape is invalid

Sample
outputShape = Shape.translate(shape, translationX, translationY)

Shape.Composite

Short description

Composite of several individual shapes. The composite contains a set of positive shapes and an optional set of negative shapes, and the final shape is the union of all positive shapes, with the union of all negative shapes removed. The order of the shapes has no significance.

Keywords

draw, rasterize, render

Functions

addShape()
Short description

Add a shape to the composite

Parameters
Name Type Description

composite

OBJECT Shape.Composite

The composite to modify

shape

CONST_OBJECT Shape

The shape to add

isPositive

BOOL

True means positive shape, false means negative shape (default is positive)

Sample
Shape.Composite.addShape(composite, shape, isPositive)
clone()
Short description

Create an independent deep copy of the composite

Parameters
Name Type Description

inputComposite

CONST_OBJECT Shape.Composite

Input composite

Return values
Name Type Description

outputComposite

OBJECT Shape.Composite

Deep copy of the input composite

Sample
sc2 = Shape.Composite.clone(sc)
contains()
Short description

Check if the given point is within this composite (within any of the positive shapes but not within any of the negative ones). False is returned if any invalid shape is in the composite.

Parameters
Name Type Description

composite

CONST_OBJECT Shape.Composite

Input composite

point

CONST_OBJECT Point

Point to check

Return values
Name Type Description

result

BOOL

True if the point is within the region, otherwise false

Sample
b = Shape.Composite.contains(composite, point)
create()
Short description

Create an empty shape composite

Return values
Name Type Description

composite

OBJECT Shape.Composite

The created shape composite.

Sample
sc = Shape.Composite.create()
getPositiveBoundingBox()
Short description

Get a bounding box of all positive shapes. This box is guaranteed to contain the entire region but might not be the tightest possible box if negative regions are used.

Parameters
Name Type Description

composite

CONST_OBJECT Shape.Composite

The composite to use

Return values
Name Type Description

box

OBJECT Shape

Rectangle shape representing the bounding box

Sample
box = Shape.Composite.getPositiveBoundingBox(composite)
getShape()
Short description

Get one of the shapes and its associated isNegative flag

Parameters
Name Type Description

composite

CONST_OBJECT Shape.Composite

Input shape composite

index

INT

Index of the shape to return (0-based)

Return values
Name Type Description

shape

OBJECT Shape

The requested shape

isPositive

BOOL

True if the shape is positive, otherwise false

Sample
shape, isPositive = Shape.Composite.getShape(composite, index)
getShapeCount()
Short description

Get the number of shapes contained in this composite

Parameters
Name Type Description

composite

CONST_OBJECT Shape.Composite

Input shape composite

Return values
Name Type Description

count

INT

Number of shapes in the composite (positive and negative)

Sample
n = Shape.Composite.getShapeCount(composite)
toImage()
Short description

Convert the composite shape into an image, setting pixels within the shape contour to a specific value. The value is in world coordinates and is cropped to the representable range. Pixels outside are set to pixel value zero.

Parameters
Name Type Description

composite

CONST_OBJECT Shape.Composite

Input composite

referenceImage

CONST_OBJECT Image

Image used to define world-pixel coordinate conversion and target resolution

worldValue

FLOAT

World value to use within the region. Default is 255.

Return values
Name Type Description

outputImage

OBJECT Image

The converted image

Sample
image = Shape.Composite.toImage(shapeComposite, referenceImage, worldValue)
toPixelRegion()
Short description

Convert a shape composite to a pixel region. This is useful for showing the composite in a viewer, or to use the composite region as input to image processing methods.

Parameters
Name Type Description

composite

CONST_OBJECT Shape.Composite

Composite shape region to convert.

referenceImage

CONST_OBJECT Image

Reference image, defines the image world coordinate system.

Return values
Name Type Description

outputRegion

OBJECT Image.PixelRegion

Input composite converted to a PixelRegion.

Sample
pixelRegion = Shape.Composite.toPixelRegion(composite, referenceImage)
toPolygons()
Short description

Convert the shape composite to a composite consisting only of polygons. All circle and ellipses in the input are approximated by polygons with a given maximum error.

Parameters
Name Type Description

inputComposite

CONST_OBJECT Shape.Composite

Input composite

epsilon

FLOAT

Maximum approximation error. Controls the number of points used in the polygon approximation of ellipses and circles

maxPoints

INT

Maximum number of points to use in the approximation if each polygon (default is 1000). This is a stronger requirement than the epsilon and puts a limit on the function memory usage.

Return values
Name Type Description

outputComposite

OBJECT Shape.Composite

Polygon composite shape.

Sample
outputComposite = Shape.Composite.toPolygons(inputComposite, epsilon)
toString()
Short description

Gets a user-friendly string description of the composite shape.

Parameters
Name Type Description

composite

CONST_OBJECT [API:DataFormat:]

The composite shape to describe.

Return values
Name Type Description

str

STRING

User-friendly description of the composite shape .

Sample
str = Shape.Composite.toString(composite)
transform()
Short description

Transform the composite according to a general 2D transformation. Requires that all individual shapes support the transformation. For example, if one of the shapes is a circle and the transformation is an affine transformation, the operation will fail, since circles are no longer circles after an affine transformation. For transforming any kind of composite, consider converting the composite to a polygon representation using toPolygons first.

Parameters
Name Type Description

composite

CONST_OBJECT Shape.Composite

Input shape composite

transform

CONST_OBJECT Transform

The transform to use (must be a 2D transform)

Return values
Name Type Description

newComposite

OBJECT Shape.Composite

The transformed shape composite

Sample
newComposite = Shape.Composite.transform(composite, transform)

Shape3D

Short description

A 3D geometric primitive, e.g., Line, LineSegment, Polyline, Plane, Rectangle, Circle, Box, Sphere, Cylinder, Cone, etc. The pose (position and orientation) of most shapes is controlled by a 3D Transform. Such shapes have a defined default pose, often centered around the origin, from which the pose transform is used to move and rotate the shape into the desired pose in 3D space. When creating a shape, the pose transform is not allowed to change the size of the shape (the size is set by specific parameters), that is, the pose transform must be of rigid, rotation or translation type. Shapes can be transformed using more general transformations, however the type of transformations allowed is specific to each shape and limited to make sure the shape stays within its class. For example, a non-uniform scaling will turn a circle into an ellipse and is thus not allowed. The Shape3D object is represented in mathematical analytical form. Operations such as finding intersection points, distances and transforming the geometric primitive are for this reason efficiently computed.

Functions

clone()
Short description

Create an independent copy of the shape. If the input is a vector of shapes, the output is a vector of shapes.

Parameters
Name Type Description

inputShape

CONST_OBJECT Shape3D

The shape to clone.

Return values
Name Type Description

outputShape

OBJECT Shape3D

The new copy.

Sample
outputShape = Shape3D.clone(inputShape)
contains()
Short description

Returns true if the supplied 3D point is within the shape. Returns false for all shapes with zero volume. If more than one shape is provided true is returned if the point is inside any of the shapes. If more than one point is provided a vector is returned with one value for each input point.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

point

CONST_OBJECT Point

The 3D point to probe.

Return values
Name Type Description

isInside

BOOL

True if the point is inside the shape.

Sample
isInside = Shape3D.contains(shape3d, point)
countInside()
Short description

Counts the number of points that fall within the shape.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

points

CONST_OBJECT Point

The 3D points to probe.

Return values
Name Type Description

count

INT

The number of points within the shape.

Sample
count = Shape3D.countInside(shape3d, points)
createBox()
Short description

Create a box in 3D space. Unless transformed, the box is centered on the origin.

Parameters
Name Type Description

sizeX

FLOAT

Size of the box in the x-direction before transformation.

sizeY

FLOAT

Size of the box in the y-direction before transformation.

sizeZ

FLOAT

Size of the box in the z-direction before transformation.

poseTransform

CONST_OBJECT Transform

Transform defining the box position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name Type Description

box

OBJECT Shape3D

The created box.

Sample
box = Shape3D.createBox(sizeX, sizeY, sizeZ, poseTransform)
createCircle()
Short description

Create a 2D circle embedded in 3D space. Unless transformed, the circle is created in the xy-plane, centered on the origin.

Parameters
Name Type Description

radius

FLOAT

Radius of the circle.

poseTransform

CONST_OBJECT Transform

Transform defining the circle position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name Type Description

circle

OBJECT Shape3D

The created 3D circle.

Sample
circle = Shape3D.createCircle(radius, poseTransform)
createCone()
Short description

Create a cone in 3D space. Unless transformed, the z-axis is the symmetry axis of the cone, the base circle is centered on the origin and the apex is at the point (0, 0, heightZ).

Parameters
Name Type Description

radius

FLOAT

Largest radius of the cone.

heightZ

FLOAT

Height of the cone in the z-direction before transformation.

poseTransform

CONST_OBJECT Transform

Transform defining the cone position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name Type Description

cone

OBJECT Shape3D

The created cone.

Sample
cone = Shape3D.createCone(radius, heightZ, poseTransform)
createCylinder()
Short description

Create a cylinder in 3D space. Unless transformed, the cylinder is centered on the origin with the z-axis as symmetry line.

Parameters
Name Type Description

radius

FLOAT

Radius in the xy-plane before transformation.

heightZ

FLOAT

Height of the cylinder in the z-direction before transformation.

poseTransform

CONST_OBJECT Transform

Transform defining the cylinder position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name Type Description

cylinder

OBJECT Shape3D

The created cylinder.

Sample
cylinder = Shape3D.createCylinder(radius, heightZ, poseTransform)
createEllipse()
Short description

Create a 2D ellipse embedded in 3D space. Unless transformed, the ellipse is created in the xy-plane, centered on the origin.

Parameters
Name Type Description

radiusX

FLOAT

Radius of the ellipse in the x-direction before transformation.

radiusY

FLOAT

Radius of the ellipse in the y-direction before transformation.

poseTransform

CONST_OBJECT Transform

Transform defining the ellipse position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name Type Description

ellipse

OBJECT Shape3D

The created 3D ellipse.

Sample
ellipse = Shape3D.createEllipse(radiusX, radiusY, poseTransform)
createEllipticCylinder()
Short description

Create an elliptic cylinder in 3D space. Unless transformed, the elliptic cylinder is centered on the origin centered on the z-axis.

Parameters
Name Type Description

radiusX

FLOAT

Radius in the x-direction before transformation.

radiusY

FLOAT

Radius in the y-direction before transformation.

heightZ

FLOAT

Height of the elliptic cylinder in the z-direction before transformation.

poseTransform

CONST_OBJECT Transform

Transform defining the elliptic cylinder position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name Type Description

ellipticCylinder

OBJECT Shape3D

The created elliptic cylinder.

Sample
ellipticCylinder = Shape3D.createEllipticCylinder(radiusX, radiusY, heightZ, poseTransform)
createLine()
Short description

Create a line in 3D, passing through the two given 3D points.

Parameters
Name Type Description

point1

CONST_OBJECT Point

First 3D point on the line.

point2

CONST_OBJECT Point

Second 3D point on the line.

Return values
Name Type Description

line

OBJECT Shape3D

The created 3D line, or nil if the two point coincide.

Sample
line = Shape3D.createLine(point1, point2)
createLineSegment()
Short description

Create a line segment in 3D between the two given 3D points.

Parameters
Name Type Description

point1

CONST_OBJECT Point

First 3D endpoint of the line segment.

point2

CONST_OBJECT Point

Second 3D endpoint of the line segment.

Return values
Name Type Description

lineSegment

OBJECT Shape3D

The created 3D line segment, or nil if the two point coincide.

Sample
lineSegment = Shape3D.createLineSegment(point1, point2)
createPlane()
Short description

Create a plane in 3D. A plane is defined by its normal vector (vector perpendicular to the plane) and a distance from the world origin (Hesse normal form). For example, an XY-aligned plane at Z = 5 is constructed using Shape3D.createPlane(0, 0, 1, 5). The distance is signed and measured from the origin along the normal. A plane where the normal points from the plane towards the origin has a negative distance.

Parameters
Name Type Description

nx

FLOAT

X component of plane normal vector.

ny

FLOAT

Y component of plane normal vector.

nz

FLOAT

Z component of plane normal vector.

distance

FLOAT

Distance from the origin to the plane along the plane normal.

Return values
Name Type Description

plane

OBJECT Shape3D

The created plane, or nil if the normal vector was a zero vector.

Sample
plane = Shape3D.createPlane(nx, ny, nz, distance)
createPlaneFromPoints()
Short description

Create a plane in 3D containing the three given 3D points. The three points must span a plane, i.e., they must not be distributed along a line.

Parameters
Name Type Description

point1

CONST_OBJECT Point

First 3D point.

point2

CONST_OBJECT Point

Second 3D point.

point3

CONST_OBJECT Point

Third 3D point.

Return values
Name Type Description

plane

OBJECT Shape3D

The created plane, or nil if the points are in a degenerate configuration.

Sample
plane = Shape3D.createPlaneFromPoints(point1, point2, point3)
createPolygon()
Short description

Create a 2D closed polygon embedded in 3D space. If the points are not in a plane, the points are projected onto the best fitting plane. At least three points are required.

Parameters
Name Type Description

points

CONST_OBJECT Point

Corner points for the polygon.

Return values
Name Type Description

polygon

OBJECT Shape3D

The created 2D polygon in 3D.

Sample
polygon = Shape3D.createPolygon(points)
createPolyline()
Short description

Create a full 3D polyline. Corners can be placed freely in 3D, however, a closed surface for a general 3D polyline would be ambiguous and thus this shape can not be closed. Use the 3D polygon for closed shapes.

Parameters
Name Type Description

points

CONST_OBJECT Point

Corner points for the polyline.

Return values
Name Type Description

polyline

OBJECT Shape3D

The created polyline.

Sample
polyline = Shape3D.createPolyline(points)
createRectangle()
Short description

Create a 2D rectangle embedded in 3D space. Unless transformed, the rectangle is created in the xy-plane, centered on the origin.

Parameters
Name Type Description

sizeX

FLOAT

Size of the rectangle in the x-direction before transformation (width).

sizeY

FLOAT

Size of the rectangle in the y-direction before transformation (height).

poseTransform

CONST_OBJECT Transform

Transform defining the rectangle position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform.

Return values
Name Type Description

rectangle

OBJECT Shape3D

The created 3D rectangle.

Sample
rectangle = Shape3D.createRectangle(sizeX, sizeY, poseTransform)
createSphere()
Short description

Create a sphere in 3D space. Unless transformed, the sphere is centered on the origin.

Parameters
Name Type Description

radius

FLOAT

Radius of the sphere.

poseTransform

CONST_OBJECT Transform

Transform defining the sphere position and orientation in 3D space. Must be of type identity, translation or rigid. The sphere itself is invariant to rotations however the orientation of the local coordinate system is affected. Optional, default is an identity transform.

Return values
Name Type Description

sphere

OBJECT Shape3D

The created sphere.

Sample
sphere = Shape3D.createSphere(radius, poseTransform)
cropLine()
Short description

Returns the part of a line within a box as a new line segment. If the line does not intersect the box, nil is returned.

Parameters
Name Type Description

line

CONST_OBJECT Shape3D

The line shape to be cropped.

box

CONST_OBJECT Shape3D

The box to crop the line with.

Return values
Name Type Description

line

OBJECT Shape3D

The part of the line within the box as a line segment.

Sample
lineSegment = Shape3D.cropLine(line, box)
fitLine()
Short description

Fit a 3D line to a set of 3D-points. Different fitting and outlier handling modes are available. Fitting mode may be any of: LEASTSQUARES - Ordinary least squares, fast but not robust against outliers. RANSAC - Outlier rejection by random sampling and consensus. The trade-off between speed and robustness can be adjusted using an iteration parameter. TRIMMED - Two stages of least squares fitting with outlier rejection between the stages. Performance is in general in between RANSAC and least squares with respect to robustness and speed. For RANSAC and trimmed modes, outliers are specified with a margin parameter in one of the following ways: ABSOLUTE - Absolute outlier margin, points with a distance larger than the specified distance from the line are treated as outliers. RANK - Defines the fraction of points to treat as inlier points. For example, a rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored as outliers. If there are additional points close to the margin, those will also be included such that the final inlier fraction may be higher.

Parameters
Name Type Description

points

CONST_OBJECT Point

Input points.

mode

ENUM Shape3D.ShapePointFitMode

Fitting mode. Default is LEASTSQUARES.

marginType

ENUM Shape.OutlierMarginType

Outlier margin type (ABSOLUTE or RANK). Only used in fitting modes: RANSAC and TRIMMED. Default is ABSOLUTE.

margin

FLOAT

Inlier margin, the interpretation depends on the margin type. Only used in iterative fitting modes: RANSAC and TRIMMED. Default is 2.0 for ABSOLUTE and 0.5 for RANK.

iterations

INT

Number of iterations. Only used in iterative fitting mode: RANSAC.

Return values
Name Type Description

line

OBJECT Shape3D

The 3D line with best fit.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the line.

Sample
line3d, quality = Shape3D.fitLine(points, mode, margin, iterations)
fitPlane()
Short description

Fit a plane shape to a set of 3D-points. Different fitting and outlier handling modes are available. Fitting mode may be any of: LEASTSQUARES - Ordinary least squares, fast but not robust against outliers. RANSAC - Outlier rejection by random sampling and consensus. The trade-off between speed and robustness can be adjusted using an iteration parameter. TRIMMED - Two stages of least squares fitting with outlier rejection between the stages. Performance is in general in between RANSAC and least squares with respect to robustness and speed. For RANSAC and trimmed modes, outliers are specified with a margin parameter in one of the following ways: ABSOLUTE - Absolute outlier margin, points with a distance larger than the specified distance from the plane are treated as outliers. RANK - Defines the fraction of points to treat as inlier points. For example, a rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored as outliers. If there are additional points close to the margin, those will also be included such that the final inlier fraction may be higher.

Parameters
Name Type Description

points

CONST_OBJECT Point

Input points.

mode

ENUM Shape3D.ShapePointFitMode

Fitting mode. Default is LEASTSQUARES.

marginType

ENUM Shape.OutlierMarginType

Outlier margin type (ABSOLUTE or RANK). Only used in fitting modes: RANSAC and TRIMMED. Default is ABSOLUTE.

margin

FLOAT

Inlier margin, the interpretation depends on the margin type. Only used in fitting modes: RANSAC and TRIMMED. Default is 2.0 for ABSOLUTE and 0.5 for RANK.

iterations

INT

Number of iterations. Only used in iterative fitting mode: RANSAC. Default is 20.

Return values
Name Type Description

plane

OBJECT Shape3D

Plane with best fit.

quality

FLOAT

Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the plane.

Sample
plane, quality = Shape3D.fitPlane(points, mode, margin, iterations)
getArea()
Short description

Returns the total surface area of the shape. For flat shapes, e.g., a rectangle, circle or ellipse in 3D space, only one side is counted.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

Return values
Name Type Description

area

FLOAT

The surface area of the shape.

Sample
area = Shape3D.getArea(shape3d)
getBoundingBox()
Short description

Returns the smallest axis aligned box that encloses the shape.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

Return values
Name Type Description

boundingBox

OBJECT Shape3D

The axis aligned bounding box of the shape.

Sample
boundingBox = Shape3D.getBoundingBox(shape3d)
getBounds()
Short description

Get the bounds of the shape as individual values.

Parameters
Name Type Description

shape

CONST_OBJECT Shape3D

Input shape

Return values
Name Type Description

xMin

FLOAT

Minimum x coordinate.

yMin

FLOAT

Minimum y coordinate.

zMin

FLOAT

Minimum z coordinate.

xMax

FLOAT

Maximum x coordinate.

yMax

FLOAT

Maximum y coordinate.

zMax

FLOAT

Maximum z coordinate.

Sample
xMin, yMin, zMin, xMax, yMax, zMax = Shape3D.getBounds(shape)
getBoxParameters()
Short description

Get the size and pose of the 3D box.

Parameters
Name Type Description

box

CONST_OBJECT Shape3D

The created box.

Return values
Name Type Description

sizeX

FLOAT

Size of the box in the x-direction before transformation.

sizeY

FLOAT

Size of the box in the y-direction before transformation.

sizeZ

FLOAT

Size of the box in the z-direction before transformation.

poseTransform

OBJECT Transform

Transform defining the box position and orientation in 3D space. Is of type identity, translation or rigid.

Sample
sizeX, sizeY, sizeZ, poseTransform = Shape3D.getBoxParameters(box)
getCenterOfGravity()
Short description

Returns the center of gravity of the shape. Returns nil for invalid shapes and for shapes with infinite size.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

Return values
Name Type Description

center

OBJECT Point

The center of gravity of the shape.

Sample
center = Shape3D.getCenterOfGravity(shape3d)
getCircleParameters()
Short description

Get the radius and pose of the 3D circle.

Parameters
Name Type Description

circle

OBJECT Shape3D

The 3D circle.

Return values
Name Type Description

radius

FLOAT

Radius of the circle.

poseTransform

CONST_OBJECT Transform

Transform defining the circle position and orientation in 3D space. Is of type identity, translation or rigid.

Sample
radius, poseTransform = Shape3D.getCircleParameters(circle)
getClosestSurfacePoint()
Short description

Returns the point on the shape surface (or edge) closest to the probe point. If there are more than one shape provided the closest point on any shape surface is returned. If there are more than one point provided one point is returned for each input point.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

point

CONST_OBJECT Point

The 3D point to probe.

Return values
Name Type Description

surfacePoint

OBJECT Point

The point on the surface closest to the probe point.

distance

FLOAT

The distance to the closest point.

Sample
surfacePoint = Shape3D.getClosestSurfacePoint(shape3d, point)
getConeApex()
Short description

Returns the position of the tip of the cone. Together with getCenterOfGravity, two points defining the direction of the cone can be found.

Parameters
Name Type Description

shape

CONST_OBJECT Shape3D

The cone.

Return values
Name Type Description

apex

OBJECT Point

The apex of the cone, or nil if any other shape is given.

Sample
apex = Shape3D.getConeApex(shape)
getConeParameters()
Short description

Get the radius, height and pose of a cone.

Parameters
Name Type Description

cone

OBJECT Shape3D

The cone.

Return values
Name Type Description

radius

FLOAT

The largest radius of the cone.

heightZ

FLOAT

Height of the cone from the base circle to the apex.

poseTransform

CONST_OBJECT Transform

Transform defining the cone position and orientation in 3D space. Is of type identity, translation or rigid.

Sample
radius, heightZ, poseTransform = Shape3D.getConeParameters(cone)
getCylinderParameters()
Short description

Get the radius, height and pose of a cylinder.

Parameters
Name Type Description

cylinder

OBJECT Shape3D

The created cylinder.

Return values
Name Type Description

radius

FLOAT

Radius in the xy-plane before transformation.

heightZ

FLOAT

Height of the cylinder in the z-direction before transformation.

poseTransform

CONST_OBJECT Transform

Transform defining the cylinder position and orientation in 3D space. Is of type identity, translation or rigid.

Sample
radius, heightZ, poseTransform = Shape3D.getCylinderParameters(cylinder)
getEllipseParameters()
Short description

Get the radii and pose transform of the 3D ellipse.

Parameters
Name Type Description

ellipse

OBJECT Shape3D

The 3D ellipse.

Return values
Name Type Description

radiusX

FLOAT

Radius of the ellipse in the x-direction before transformation.

radiusY

FLOAT

Radius of the ellipse in the y-direction before transformation.

poseTransform

CONST_OBJECT Transform

Transform defining the ellipse position and orientation in 3D space. Is of type identity, translation or rigid.

Sample
radiusX, radiusY, poseTransform = Shape3D.getEllipseParameters(ellipse)
getEllipticCylinderParameters()
Short description

Get the radii, height and pose of an elliptic cylinder.

Parameters
Name Type Description

ellipticCylinder

OBJECT Shape3D

The elliptic cylinder.

Return values
Name Type Description

radiusX

FLOAT

Radius in the x-direction before transformation.

radiusY

FLOAT

Radius in the y-direction before transformation.

heightZ

FLOAT

Height of the elliptic cylinder in the z-direction before transformation.

poseTransform

CONST_OBJECT Transform

Transform defining the elliptic cylinder position and orientation in 3D space. Is of type identity, translation or rigid.

Sample
radiusX, radiusY, heightZ, poseTransform = Shape3D.getEllipticCylinderParameters(ellipticCylinder)
getIntersectionAngle()
Short description

Get the sharpest angle between two flat Shape3D shapes (circle, rectangle, ellipse in 3D space, etc.), 3D lines, 3D line segments or combination thereof. The shapes do not need to intersect. The angle is in the range 0 to pi/2 where zero indicates parallel planes or lines. Shapes lying in orthogonal planes result in the angle pi/2. Nil is returned if either argument is not a flat shape or a line.

Parameters
Name Type Description

shape1

CONST_OBJECT Shape3D

Shape 1, a flat shape, line or line segment.

shape2

CONST_OBJECT Shape3D

Shape 2, a flat shape, line or line segment.

Return values
Name Type Description

angle

FLOAT

Sharpest angle between shapes, or Nil if shapes are not flat.

Sample
angle = Shape3D.getIntersectionAngle(shape1, shape2)
getIntersectionLine()
Short description

Returns the intersection line of two planes.

Parameters
Name Type Description

shape1

CONST_OBJECT Shape3D

First plane.

shape2

CONST_OBJECT Shape3D

Second plane.

Return values
Name Type Description

intersections

OBJECT Shape3D

Intersection line. If there is no intersection, an empty list is returned. If the shape combination is not supported, nil is returned.

Sample
intersections = Shape3D.getIntersectionLine(shape1, shape2)
getIntersectionPoints()
Short description

Returns the intersection points of two shapes. One of the shapes must be a line or a line segment.

Parameters
Name Type Description

shape1

CONST_OBJECT Shape3D

First shape.

shape2

CONST_OBJECT Shape3D

Second shape.

Return values
Name Type Description

intersections

OBJECT Point

Intersection points. If there are intersections, an empty list is returned. If the shape combination is not supported, nil is returned.

Sample
intersections = Shape3D.getIntersectionPoints(shape1, shape2)
getLineParameters()
Short description

Get two 3D points on the line. Note that these two points may not be the same points used for creating a line using the createLine() function as the line representation is normalized internally.

Parameters
Name Type Description

line

CONST_OBJECT Shape3D

The 3D line.

Return values
Name Type Description

point1

OBJECT Point

First 3D point on the line.

point2

OBJECT Point

Second 3D point on the line.

Sample
point1, point2 = Shape3D.getLineParameters(line)
getLineSegmentParameters()
Short description

Get the 3D end points of the line segment.

Parameters
Name Type Description

lineSegment

CONST_OBJECT Shape3D

The 3D line segment.

Return values
Name Type Description

point1

OBJECT Point

First 3D endpoint on the line segment.

point2

OBJECT Point

Second 3D endpoint on the line segment.

Sample
point1, point2 = Shape3D.getLineSegmentParameters(lineSegment)
getPlaneDistance()
Short description

Returns the minimum and maximum distance from all points on the shape to the reference plane. Distances are measured orthogonal to the reference plane. The query shape should have finite size.

Parameters
Name Type Description

shape

CONST_OBJECT Shape3D

The shape to check distance to.

referencePlane

CONST_OBJECT Shape3D

The reference plane.

Return values
Name Type Description

minDist

FLOAT

The distance from the plane to the closest point on the shape, or nil if projection failed.

maxDist

FLOAT

The orthogonal distance from the plane to the point on the shape furthest away from the plane, or nil if projection failed.

Sample
minDist, maxDist = Shape3D.getPlaneDistance(shape, referencePlane)
getPlaneParameters()
Short description

Get the parameters of the plane (normal vector plus distance). The distance is signed and measured from the origin along the normal. A plane where the normal points from the plane towards the origin has a negative distance.

Parameters
Name Type Description

plane

CONST_OBJECT Shape3D

The plane.

Return values
Name Type Description

nx

FLOAT

X component of plane normal vector.

ny

FLOAT

Y component of plane normal vector.

nz

FLOAT

Z component of plane normal vector.

distance

FLOAT

Distance from the origin to the plane along the plane normal.

Sample
nx, ny, nz, distance = Shape3D.getPlaneParameters(plane)
getPlanePoints()
Short description

Returns the point(s) on the plane at the given x,y-coordinate(s).

Parameters
Name Type Description

shape

CONST_OBJECT Shape

Input plane.

points2d

CONST_OBJECT Point

Query points.

Return values
Name Type Description

points3d

OBJECT Point

Points on plane, nil if any error occurred.

Sample
points3d = Shape3D.getPlanePoints(shape, points2d)
getPolygonParameters()
Short description

Get the points defining the polygon.

Parameters
Name Type Description

polygon

CONST_OBJECT Shape3D

The polygon.

Return values
Name Type Description

points

OBJECT Point

Corner points for the polygon.

Sample
points = Shape3D.getPolygonParameters(polygon)
getPolylineParameters()
Short description

Get the points defining the polyline.

Parameters
Name Type Description

polyline

CONST_OBJECT Shape3D

The polyline.

Return values
Name Type Description

points

OBJECT Point

Corner points for the polyline.

Sample
points = Shape3D.getPolylineParameters(polyline)
getRectangleParameters()
Short description

Get the size and pose of the 3D rectangle.

Parameters
Name Type Description

rectangle

CONST_OBJECT Shape3D

The 3D rectangle.

Return values
Name Type Description

sizeX

FLOAT

Size of the rectangle in the x-direction before transformation (width).

sizeY

FLOAT

Size of the rectangle in the y-direction before transformation (height).

poseTransform

OBJECT Transform

Transform defining the rectangle position and orientation in 3D space. Is of type identity, translation or rigid.

Sample
sizeX, sizeY, poseTransform = Shape3D.getRectangleParameters(rectangle)
getSphereParameters()
Short description

Get the radius and position of the sphere.

Parameters
Name Type Description

sphere

CONST_OBJECT Shape3D

The sphere.

Return values
Name Type Description

radius

FLOAT

Radius of the sphere.

poseTransform

OBJECT Transform

Transform defining the sphere position and orientation in 3D space. Is of type identity, translation or rigid.

Sample
radius, poseTransform = Shape3D.getSphereParameters(sphere)
getType()
Short description

Get the shape type.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

Return values
Name Type Description

shapeType

ENUM Shape3DType

The shape type.

Sample
shapeType = Shape3D.getType(shape3d)
getVolume()
Short description

Returns the volume of the shape.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

Return values
Name Type Description

volume

FLOAT

The volume of the shape.

Sample
volume = Shape3D.getVolume(shape3d)
isClosed()
Short description

Returns true if the shape has no endpoints and encloses an area.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

Return values
Name Type Description

closed

BOOL

True if the shape is closed.

Sample
closed = Shape3D.isClosed(shape3d)
isZeroVolume()
Short description

Returns true if the shape type in general has no volume, such as for 2D shapes in 3D space.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

Return values
Name Type Description

noVolume

BOOL

True if the shape has zero volume.

Sample
noVolume = Shape3D.isZeroVolume(shape3d)
projectZ()
Short description

Projects one or more Shape3D orthogonally onto the plane described by z = 0. Returns the result as one or more Shape2D together with the minimum and maximum z-values encountered. Lines, line segments, circles, ellipses, boxes, rectangles, spheres, polygons and polylines are supported.

Parameters
Name Type Description

shape

CONST_OBJECT Shape3D

Shape(s) to be projected.

Return values
Name Type Description

projectedShape

OBJECT Shape

The projected shape(s), or nil if projection failed.

zMin

FLOAT

Minimum z-value(s) of shape(s) before projection, or nil if projection failed.

zMax

FLOAT

Maximum z-value(s) of shape(s) before projection, or nil if projection failed.

Sample
projectedShape, zMin, zMax = Shape3D.projectZ(shape)
rotateX()
Short description

Rotate the shape around an axis parallel to the world x-axis. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For cones, the nominal center is the center of the base circle. For lines and planes, the nominal center is the point in the shape closest to the origin.

Parameters
Name Type Description

shape

CONST_OBJECT Shape3D

Input shape

rotationAngle

FLOAT

The rotation angle in radians

rotationCenter

CONST_OBJECT Point

The rotation center. The nominal center of the shape is used if unspecified.

Return values
Name Type Description

outputShape

OBJECT Shape3D

The rotated shape, or nil if the input shape is invalid.

Sample
outputShape = Shape3D.rotateX(shape, rotationAngle, rotationCenter)
rotateY()
Short description

Rotate the shape around an axis parallel to the world y-axis. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For cones, the nominal center is the center of the base circle. For lines and planes, the nominal center is the point in the shape closest to the origin.

Parameters
Name Type Description

shape

CONST_OBJECT Shape3D

Input shape

rotationAngle

FLOAT

The rotation angle in radians

rotationCenter

CONST_OBJECT Point

The rotation center. The nominal center of the shape is used if unspecified.

Return values
Name Type Description

outputShape

OBJECT Shape3D

The rotated shape, or nil if the input shape is invalid.

Sample
outputShape = Shape3D.rotateY(shape, rotationAngle, rotationCenter)
rotateZ()
Short description

Rotate the shape around an axis parallel to the world z-axis. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For cones, the nominal center is the center of the base circle. For lines and planes, the nominal center is the point in the shape closest to the origin.

Parameters
Name Type Description

shape

CONST_OBJECT Shape3D

Input shape

rotationAngle

FLOAT

The rotation angle in radians

rotationCenter

CONST_OBJECT Point

The rotation center. The nominal center of the shape is used if unspecified.

Return values
Name Type Description

outputShape

OBJECT Shape3D

The rotated shape, or nil if the input shape is invalid.

Sample
outputShape = Shape3D.rotateZ(shape, rotationAngle, rotationCenter)
toLine()
Short description

Extends a line segment to the the infinite line type.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

A line segment 3D shape.

Return values
Name Type Description

line

OBJECT Shape3D

The extended shape as a line.

Sample
line = Shape3D.toLine(shape3d)
toPixelRegion()
Short description

Projects the convex hull of a Shape3D (except polyLine) onto the plane z = 0 (in world coordinates) and creates the corresponding pixel region. The minimum and maximum world coordinate extent of the convex hull in the z-direction are returned. The reference image defines the pixel coordinate system to be used for the PixelRegion.

Keywords

draw, project, render, rasterize

Parameters
Name Type Description

shape

CONST_OBJECT Shape3D

The shape used to define the pixel region.

referenceImage

CONST_OBJECT Image

An image defining the coordinate system used to create the PixelRegion.

fill

BOOL

Set to true to generate a filled region, false to generate a border region. Non-closed shapes will always generate a border only.

Return values
Name Type Description

pixelRegion

OBJECT Image.PixelRegion

The projected convex hull region, or nil on error.

zMin

FLOAT

The minimum z-position of any part of the shape, in image world coordinates.

zMax

FLOAT

The maximum z-position of any part of the shape, in image world coordinates.

Sample
pixelRegion, zMin, zMax = Shape3D.toPixelRegion(shape, referenceImage)
toPlane()
Short description

Returns the plane which a flat shape span, such as rectangles, circles and polygons. Not defined for a line type shape.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

A flat 3D shape input.

Return values
Name Type Description

plane

OBJECT Shape3D

The plane containing the flat 3D shape.

Sample
plane = Shape3D.toPlane(shape3d)
toPolygon()
Short description

Approximates a flat closed shape in 3D as a polygon.

Parameters
Name Type Description

shape

CONST_OBJECT Shape3D

Shape to be approximated.

epsilon

FLOAT

Maximum approximation error in the polygon approximation.

maxPoints

INT

Maximum number of points to use in the approximation (default is 1000). This is a stronger requirement than the epsilon and puts a limit on the function memory usage.

Return values
Name Type Description

polygon

OBJECT Shape3D

The shape as a polygon, or nil if the shape is invalid or non-flat.

Sample
polygon = Shape3D.toPolygon(shape, epsilon, maxPoints)
toString()
Short description

Get a user-friendly string description of the 3D shape.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

Return values
Name Type Description

str

STRING

User-friendly string description.

Sample
print(Shape3D.toString(shape3d))
transform()
Short description

Transforms a single shape or a vector of shapes according to the supplied transform. The transform must not change the type of the geometric primitive, e.g., it is not possible to transform a sphere using an affine transform as the result may not be a sphere anymore. The pose transform of shapes are kept as non-mirroring rigid transforms, made to always generate a right-handed orthonormal local coordinate system. Transforming a shape with a similarity transform will decompose the transform and apply the scaling component directly to the size of the shape. Similarly, a transform containing a mirroring component will be reformulated to get the mirroring aligned with a symmetry plane of the shape, where it has no effect on the shape and will be removed. Thus the shape will be correctly transformed, however fetching the pose transform of a shape may not return the transform used to transform the shape.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

transform

CONST_OBJECT Transform

The transform to apply.

Return values
Name Type Description

transformedShape

OBJECT Shape3D

The transformed shape.

Sample
transformedShape = Shape3D.transform(shape3d, transform)
translate()
Short description

Translate the shape, i.e., shift it along the x,y,z directions.

Parameters
Name Type Description

shape3d

CONST_OBJECT Shape3D

3D shape input.

translationX

FLOAT

The translation along the X-axis.

translationY

FLOAT

The translation along the Y-axis.

translationZ

FLOAT

The translation along the Z-axis.

Return values
Name Type Description

outputShape

OBJECT Shape3D

The translated shape, or nil if the input shape is invalid.

Sample
outputShape = Shape3D.translate(shape3d, translationX, translationY, translationZ)

Statistics

Short description

Functions for computing statistics of 1D numeric arrays, signals, time series, histograms etc. For example mean, standard deviation, correlation, comparing histograms. More functions for 1D data analysis is under the Profile API.

See also

Functions

compareHistograms()
Short description

Compare two histograms of equal size. If the histograms are obtained from regions of different sizes, they should be normalized first.

Parameters
Name Type Description

histogram1

FLOAT

First histogram to compare

histogram2

FLOAT

Second histogram to compare

method

ENUM HistogramCompareMethod

Comparison method (default is Chi-squared statistic)

Return values
Name Type Description

distance

FLOAT

Distance measure of the two histograms. Zero if they are equal and larger the more different the histograms are.

Sample
distance = Statistics.compareHistograms(histogram1, histogram2)
normalizeHistogram()
Short description

Normalize a histogram. If no bin centers are specified, the histogram is normalized such that the sum of all values is 1. If centers is specified, it is instead normalized such that the integral over the value domain is 1.

Parameters
Name Type Description

inputHistogram

FLOAT

Input histogram

centers

FLOAT

Optional bin centers. Must be equally spaced. Typically, the bin centers are returned from the method that produced the histogram in the first place.

Return values
Name Type Description

outputHistogram

FLOAT

Output histogram, normalized to unit sum

Sample
outputHistogram = Statistics.normalizeHistogram(inputHistogram)

TCPIPClient

Short description

Provides raw TCIP/IP connections to servers. First a new TCPIPClient needs to be created using the create function. Afterwards the IP address and the port must be set using the set-functions. Then a call to the connect-function starts the connection tries to the server. If the connection gets disconnected it is tried to established it again automatically. Connects and disconnects can be detected by a register to the OnConnect and OnDisconnect events or by polling the IsConnected function. Failed transmits are a sign of broken connection and user could also call disconnect manually. Data could be transmitted to the server using the "transmit" function. Data could be received by a register to the "OnReceive" event or by calling the blocking receive()-function. The transmitted and received data is raw data. It could get automatically framed for transmitting and receiving can be automatically parsed if setting a framing with the "setFraming" function. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.

Keywords

Ethernet

See also

Functions

connect()
Short description

Starts trying to connect to the server. The OnConnected and OnDisconnected events are thrown every time the connection gets connected or disconnected. If the client gets disconnected, the client automatically tries to reconnect every 5 seconds in the background. So the connect function does not need to be called in OnDisconnect.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

timeoutMs

INT

The timeout to wait initially until the client gets connected. If not set, 500ms is the default. Check IsConnected afterwards if was successful.

Sample
TCPIPClient.connect(handle)
create()
Short description

Creates a new TCP/IP client instance. Client stays active as long as this handle exists.

Return values
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

Sample
handle = TCPIPClient.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

disconnect()
Short description

Forces a disconnect from the server

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

Sample
TCPIPClient.disconnect(handle)
isConnected()
Short description

Returns true if the client is connected

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

Return values
Name Type Description

isConnected

BOOL

True if the client is connected

Sample
bConnected = TCPIPClient.isConnected(handle)
receive()
Short description

Receives data from the client with a specified timeout. If timeout is zero then it directly returns. The data could be framed if the "setFraming" function was called before. Incoming data between multiple receive calls is queued per message. There is a fix receive queue size of 10 packets per default and can be changed using the setReceiveQueueSize()-function. More data is discarded.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

timeout

INT

Timeout in ms to wait for received data. 0 is default and means directly return.

Return values
Name Type Description

data

BINARY

The data which was received

Sample
local data = TCPIPClient.receive(handle, 1000)
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

setFraming()
Short description

Sets the framing which is to be used. If not set the default framing is no framing (raw byte/packet-wise connection). Framing could be also explicitly disabled by calling this function with 2 empty binary data for rx and tx. One framing part could be maximum size of 9 bytes. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

rxStart

BINARY

Start framing for receiving, could be empty string. Maximum size of 9.

rxStop

BINARY

Stop framing for receiving. If empty then all raw data is received. Maximum size of 9.

txStart

BINARY

Start framing for sending, could be empty string. Maximum size of 9.

txStop

BINARY

Stop framing for sending, could be empty string. Maximum size of 9.

Sample
TCPIPClient.setFraming(handle, "\02", "\03", "", "\013\010") -- STX...ETX for receiving and ...CR/LF for transmitting
setFramingBufferSize()
Short description

Sets the size of the internal framing parser buffer which is used if there is a rx or tx framing set using the setFraming function. If the rx or tx framing isn’t set, its buffer size has no effect. This size is the maximum size of a packet which can be parsed by the framing. The size is used for start and stop framing. Default is 10240 bytes.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

rxBufSize

INT

The new framing buffer size for framed receiving.

txBufSize

INT

The new framing buffer size for framed transmitting.

Sample
TCPIPClient.setFramingBufferSize(handle, 21000, 21000)
setIPAddress()
Short description

Sets the server ip address to connect to

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

ipAddress

STRING

The IP Address as string e.g. '192.168.0.10'

Sample
TCPIPClient.setIPAddress(handle, "127.0.0.1")
setInterface()
Short description

Sets the interface to use for connecting.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

ifName

ENUM EthernetInterfaces

One of the available interfaces

Sample
TCPIPClient.setInterface(handle, "ETH1")
setPort()
Short description

Sets the server port to connect to.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

port

INT

The server port between 1 and 65535

Sample
TCPIPClient.setPort(handle, 2120)
setReceiveQueueSize()
Short description

Sets the internal queue size for the receive()-function. Default is 10 packets and discarding the oldest item and warn if overrun occurs. Set to 0 to disable the queue and receiving from the receive()-function, which also increases performance if only receiving over OnReceive-event.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

queueSize

INT

The new receive queue size.

bDiscardIfFull

BOOL

Set to true to discard the newest item which is currently added instead of discarding the oldest element. Default is false.

warnOverruns

BOOL

Set to false to disable warning on overruns when using the receive()-function. Default is true.

Sample
TCPIPClient.setReceiveQueueSize(handle, 50)
setStaticSourcePort()
Short description

Sets a static source port for the TCP/IP client. If this function is not used, the default behavior of the operating system is to select a free source port automatically. Do not use this function unless a custom protocol requires a static client port.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

port

INT

The client source port between 1 and 65535

Sample
TCPIPClient.setStaticSourcePort(handle, 2120)
setTransmitTimeout()
Short description

Sets the timeout for transmits in milliseconds.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

timeoutMs

INT

The timeout for transmits in milliseconds.

Sample
TCPIPClient.setTransmitTimeout(handle, 5000)
transmit()
Short description

Transmits data to the server. If framing is set using the "setFraming" function, then the framing characters are automatically prefixed and suffixed to the transmitted data. Blocks until data has been transmitted. If transmit fails the return number of transmitted bytes is zero. If transmit fails the connection might be broken. The TCPIPClient would connect automatically again, but the user could also call disconnect()+connect() functions manually.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Client

data

BINARY

The data which is to be transmitted

Return values
Name Type Description

numberOfBytesTransmitted

INT

Number of bytes transmitted; 0 if transmit failed

Sample
TCPIPClient.transmit(handle,"Hello Server")

Events

OnConnected
Short description

The on connected event which is thrown for every connect.

Parameters
Name Type Description

handle

HANDLE

This is a handle event and must be registered on the handle

OnDisconnected
Short description

The on disconnected event which is thrown for every disconnect. The client automatically tries to connect again every 5 seconds, so the connect() function does not need to be called here.

Parameters
Name Type Description

handle

HANDLE

This is a handle event and must be registered on the handle

OnReceive
Short description

The on receive event which is thrown for every new received data.

Parameters
Name Type Description

handle

HANDLE

This is a handle event and must be registered on the handle

data

BINARY

The received data

TCPIPServer

Short description

Provides possibility to open new TCP/IP server ports at the device. A TCP/IP Server must be created using the create-function and a port must be set using the setPort-function. After a call to the listen-function the server waits for new incoming connections. If new connections arrive, the "OnConnectionAccepted" event is thrown. The user has to call then the accept function to accept the connection. Every accepted connection has its one connection handle. On the connection handle the user could receive and transmit. Currently the number of maximum parallel connections is set to 10 per default and can be changed over the setMaxConnections-function. Further connections will be automatically rejected. If new data arrives on the connection, the "OnReceive" event of the TCP/IP server is thrown with the connection handle, which received data, and the received data as parameter. The connection can be closed by the server side by calling the "TCPIPServer.Connection.close" function. If the connection is closed by the peer or by the server side, the "OnConnectionClosed" event is thrown with the connection handle of the closed connection. The transmitted and received data is raw data. It could get automatically framed for transmitting and receiving can be automatically parsed if setting a framing with the "setFraming" function. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.

Keywords

Ethernet

See also

Functions

create()
Short description

Creates a new TCP/IP server instance. Server stays active as long as this handle exists.

Return values
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Server

Sample
handle = TCPIPServer.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

listen()
Short description

Starts listening for new connections on the port. Remember to register for new connections before calling this function. If port or framing is changed, this function needs to be called to apply the settings and wait for connections on the changed port. The OnConnectionClosed function is called for existing accepted connections.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Server

Return values
Name Type Description

success

BOOL

Returns true if the listening on the port was successful

Sample
TCPIPServer.listen(handle)
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

setFraming()
Short description

Sets the framing which is to be used. If not set the default framing is no framing (raw byte/packet-wise connection). Framing could be also explicitly disabled by calling this function with 2 empty binary data for rx and tx. One framing part could be maximum size of 9 bytes. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded. The listen function has to be called afterwards so that the setting gets active.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Server

rxStart

BINARY

Start framing for receiving, could be empty string. Maximum size of 9.

rxStop

BINARY

Stop framing for receiving. If empty then all raw data is received. Maximum size of 9.

txStart

BINARY

Start framing for sending, could be empty string. Maximum size of 9.

txStop

BINARY

Stop framing for sending, could be empty string. Maximum size of 9.

Sample
TCPIPServer.setFraming(handle, "\02", "\03", "", "\013\010") -- STX...ETX for receiving and ...CR/LF for transmitting
setFramingBufferSize()
Short description

Sets the size of the internal framing parser buffer which is used if there is a rx or tx framing set using the setFraming function. If the rx or tx framing isn’t set, its buffer size has no effect. This size is the maximum size of a packet which can be parsed by the framing. The size is used for start and stop framing. Default is 10240 bytes. The listen function has to be called afterwards so that the setting gets active

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Server

rxBufSize

INT

The new framing buffer size for framed receiving.

txBufSize

INT

The new framing buffer size for framed transmitting.

Sample
TCPIPServer.setFramingBufferSize(handle, 21000, 21000)
setInterface()
Short description

Sets the interface to use for listening. The listen function has to be called afterwards so that the setting gets active.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Server

ifName

ENUM EthernetInterfaces

One of the available interfaces

Sample
TCPIPServer.setInterface(handle, "ETH1")
setMaxConnections()
Short description

Sets the number of maximum parallel active connections. Further active connections are automatically discarded. The default is set to 10 connections. The listen function has to be called afterwards so that the setting gets active.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Server

maxCons

INT

The max number of parallel active connections.

Sample
TCPIPServer.setMaxConnections(handle, 5)
setPort()
Short description

Sets the server port which is to be used. The listen function has to be called afterwards so that the setting gets active.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Server

port

INT

The server port between 1 and 65535

Sample
TCPIPServer.setPort(handle, 2120)
setTransmitTimeout()
Short description

Sets the timeout for transmits in milliseconds.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the TCP/IP Server

timeoutMs

INT

The timeout for transmits in milliseconds.

Sample
TCPIPServer.setTransmitTimeout(handle, 5000)

Events

OnConnectionAccepted
Short description

This event is thrown for every new connection which was accepted. The new connection is hold until the connected peer disconnects or the connection is rejected. To reject a connection, the function Connection.close can be called.

Parameters
Name Type Description

handle

HANDLE

This is a handle event and must be registered on the handle

conHandle

HANDLE

The connection handle of the connection which is opened

OnConnectionClosed
Short description

This event is thrown if a connection is closed by the connected peer. The connection handle is not usable anymore. The event is not thrown if the Connection.close function was called.

Parameters
Name Type Description

handle

HANDLE

This is a handle event and must be registered on the handle

conHandle

HANDLE

The connection handle of the connection which is closed

OnReceive
Short description

The on receive event which is thrown for every new received data.

Parameters
Name Type Description

handle

HANDLE

This is a handle event and must be registered on the handle

conHandle

HANDLE

The connection handle of the connection which is closed

data

BINARY

The received data. If a framing is set, only contains the content without the framing.

TCPIPServer.Connection

Short description

Controls one connection of the TCP/IP Server. To close the connection just set the handle to nil.

Functions

close()
Short description

Closes the connection explicitly from the server side. The OnConnectionClosed event is not thrown.

Parameters
Name Type Description

conHandle

HANDLE

The instance handle of the TCP/IP Server connection

Sample
TCPIPServer.Connection.close(conHandle)
getPeerAddress()
Short description

Returns the IP address and port of the connected peer on this connection.

Parameters
Name Type Description

conHandle

HANDLE

The instance handle of the TCP/IP Server connection

Return values
Name Type Description

ipAddr

STRING

The IP address of the connected peer. Nil if not available.

portNo

INT

The port number of the connected peer. Nil if not available.

Sample
local ip, port = TCPIPServer.Connection.getPeerAddress(conHandle)
isConnected()
Short description

Returns true if the client connection is still connected

Parameters
Name Type Description

conHandle

HANDLE

The instance handle of the TCP/IP Server connection

Return values
Name Type Description

isConnected

BOOL

True if the client is connected

Sample
local bConnected = TCPIPServer.Connection.isConnected(conHandle)
transmit()
Short description

Transmits data to the clients. If framing is set using the "setFraming" function, then the framing characters are automatically prefixed and suffixed to the transmitted data. Blocks until data has been transmitted.

Parameters
Name Type Description

conHandle

HANDLE

The instance handle of the TCP/IP Server connection

data

BINARY

The data which is to be transmitted

Return values
Name Type Description

numberOfBytesTransmitted

INT

Number of bytes transmitted; 0 if transmit failed

Sample
TCPIPServer.Connection.transmit(conHandle, "Hello Server")

Text

Short description

Iconic object used for displaying text in a View. Deprecated, please use plain strings and a TextDecoration object instead.

Functions

create()
Short description

Creates a new Text.

Return values
Name Type Description

text

OBJECT Text

A new text

Sample
text = Text.create()
setPosition()
Short description

Set the text position.

Parameters
Name Type Description

text

OBJECT Text

The instance to be used.

posX

INT

X

posY

INT

Y

posZ

INT

Z (only useful if 3D viewer is used).

Sample
Text.setPosition(text, 10, 10)
setSize()
Short description

Set the font size.

Parameters
Name Type Description

text

OBJECT Text

The instance to be used.

fonSize

INT

The font size.

lineSpacing

FLOAT

The line spacing in % of the font-size. Default is 1.1

Sample
Text.setSize(text, 10)
setText()
Short description

Set the textual content.

Parameters
Name Type Description

text

OBJECT Text

The instance to be used.

textstring

STRING

The text

Sample
Text.setText(text, "This is a text.")

Timer

Short description

Provides Timers which can expire and call automatically callbacks. Timers can run once or automatically periodic

Functions

create()
Short description

Sets up a timer with a specific expiration timer time after which the specified callback function is called automatically. Timer needs to be started explicitly.

Return values
Name Type Description

handle

HANDLE

Unique handle for the timer

Sample
handle = Timer.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

setExpirationTime()
Short description

Sets the expiration time of the timer in milliseconds. Default is 5000. New time is used next time calling start().

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

timeMS

INT

The expire time of the timer in milliseconds. Must be greater than 0.

Sample
Timer.setExpirationTime(handle, 5000)
setPeriodic()
Short description

Sets the timer to periodic. Default is not periodic.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

isPeriodic

BOOL

True if timer occurs periodically until it is stopped or destroyed. Default is false.

Sample
Timer.setPeriodic(handle, true)
start()
Short description

Starts the timer

Parameters
Name Type Description

handle

HANDLE

The instance to use

Sample
Timer.start(handle)
stop()
Short description

Stops the timer

Parameters
Name Type Description

handle

HANDLE

The instance to use

Sample
Timer.stop(handle)

Events

OnExpired
Short description

This event is thrown every time the timer expires

Parameters
Name Type Description

handle

HANDLE

This is a handle event and must be registered on the handle

Sample
Timer.register(handle, "OnExpired", "handleExpired")

Transform

Short description

Object representing a linear transform in 2D or 3D space.

Functions

clone()
Short description

Duplicates the transform.

Parameters
Name Type Description

transform

CONST_OBJECT Transform

The instance to use

Return values
Name Type Description

clone

OBJECT Transform

The duplicated transform

Sample
local clonedTransform = Transform.clone(transform)
compose()
Short description

Composes two transforms of the same dimensionality.

Parameters
Name Type Description

transformA

CONST_OBJECT Transform

The instance to use

transformB

CONST_OBJECT Transform

The instance to use

Return values
Name Type Description

composedTransform

OBJECT Transform

The composed transformation matrix.

Sample
local composedTransform = Transform.compose(transformA, transformB)
createFromMatrix2D()
Short description

Creates a 2D transform directly from a 3x3 matrix representation.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

A 3x3 matrix with the transform.

desiredType

ENUM TransformType

The desired transform type. If the numerical properties of the matrix does not fit the desired type, nil is returned. Optional, if not specified, the transform type is found by a numerical evaluation of the matrix.

Return values
Name Type Description

transform

OBJECT Transform

The new 2D transform.

Sample
local transform = Transform.createFromMatrix2D(matrix, desiredType)
createFromMatrix3D()
Short description

Creates a 3D transform directly from a 4x4 matrix representation.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

A 4x4 matrix with the transform.

desiredType

ENUM TransformType

The desired transform type. If the numerical properties of the matrix does not fit the desired type, nil is returned. Optional, if not specified, the transform type is found by a numerical evaluation of the matrix.

Return values
Name Type Description

transform

OBJECT Transform

The new 3D transform.

Sample
local transform = Transform.createFromMatrix3D(matrix, desiredType)
createHomography2D()
Short description

Creates a 2D homography/projective transform.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

A 3x3 matrix with the full homography transform.

Return values
Name Type Description

homographyTransform

OBJECT Transform

The new 2D homography transform

Sample
local homographyTransform = Transform.createHomography2D(matrix)
createHomography2DFromPoints()
Short description

Creates a homography/projective transform from N corresponding point pairs, source and destination points need to be of equal length. If more than 4 points are given an RANSAC estimation of the homography is performed. If either margin or iterations is set to zero all points provided will be used.

Parameters
Name Type Description

srcPoints

CONST_OBJECT Point

N source points.

dstPoints

CONST_OBJECT Point

N destination points.

margin

FLOAT

Margin expressed in world-units. Points which after transformation is within the margin is considered as inliers. Default value is 1.0. If the certainty of the points is high the margin can be lowered to reject more outliers.

iterations

INT

Number of iterations in the RANSAC loop in the homography estimation. Default value is 100. If set to 0 a least-squares estimation is performed.

Return values
Name Type Description

homographyTransform

OBJECT Transform

Homography transform.

Sample
local homographyTransform = Transform.createHomography2DFromPoints(srcPoints, dstPoints, margin, iterations)
createHomography3D()
Short description

Creates a 3D homography/projective transform.

Parameters
Name Type Description

matrix

CONST_OBJECT Matrix

A 4x4 matrix with the full homography transform.

Return values
Name Type Description

homographyTransform

OBJECT Transform

The new 3D homography transform

Sample
local homographyTransform = Transform.createHomography3D(matrix)
createIdentity2D()
Short description

Creates a new 2D transform with no rotation, scale or translation.

Return values
Name Type Description

transform

OBJECT Transform

The new 2D identity transform

Sample
local transform = Transform.createIdentity2D()
createIdentity3D()
Short description

Creates a new 3D transform with no rotation, scale or translation.

Return values
Name Type Description

transform

OBJECT Transform

The new 3D identity transform

Sample
local transform = Transform.createIdentity3D()
createReflection2D()
Short description

Creates a 2D rigid transform that is a reflection in the given 2D line.

Keywords

mirror

Parameters
Name Type Description

line

CONST_OBJECT Shape

The reflection 2D line.

Return values
Name Type Description

reflection

OBJECT Transform

The new 2D reflection transform which is of RIGID type.

Sample
local reflection = Transform.createReflection2D(line)
createReflection3D()
Short description

Creates a 3D rigid transform that is a reflection in the given 3D plane.

Parameters
Name Type Description

plane

CONST_OBJECT Shape3D

The reflection 3D plane.

Return values
Name Type Description

reflection

OBJECT Transform

The new 3D reflection transform which is of RIGID type.

Sample
local reflection = Transform.createReflection3D(plane)
createRigid2D()
Short description

Creates a 2D rigid transform with only rotation and translation.

Parameters
Name Type Description

rotation

FLOAT

Counter clockwise rotation (in radians)

xTrans

FLOAT

Translation in the x direction

yTrans

FLOAT

Translation in the y direction

origin

CONST_OBJECT Point

Optional origin of rotation if other than (0,0)

Return values
Name Type Description

rigidTransform

OBJECT Transform

The new 2D rigid transform

Sample
local rigidTransform = Transform.createRigid2D(math.pi/2, xTrans, yTrans, origin)
createRigidAxisAngle3D()
Short description

Creates a 3D rigid transform by defining an axis, a rotation around the axis and a translation.

Parameters
Name Type Description

axis

FLOAT

The rotation axis to rotate about.

rotation

FLOAT

Clockwise rotation when looking along the axis (in radians)

xTrans

FLOAT

Translation in the x direction

yTrans

FLOAT

Translation in the y direction

zTrans

FLOAT

Translation in the z direction

origin

CONST_OBJECT Point

Optional origin of rotation if other than (0,0,0)

Return values
Name Type Description

rigidTransform

OBJECT Transform

The new 3D rigid transform

Sample
local rigidTransform = Transform.createRigidAxisAngle3D({xAxis, yAxis, zAxis}, rotation, xTrans, yTrans, zTrans, origin)
createRigidEuler3D()
Short description

Creates a 3D rigid transform using Euler angles and translation. Rotations are parameterized and applied in the order specified by the rotation order. E.g. using order "XYZ", the object is first rotated alpha radians around the world x-axis, then beta radians around the world y-axis, and finally gamma radians around the world z-axis. All rotations are according to the right hand rule, positive is clockwise when looking along the direction of the rotation axis.

Parameters
Name Type Description

rotationOrder

ENUM RotationOrder

Order in which to apply rotations and order of rotation parameters.

alpha

FLOAT

Rotation around the first axis (in radians).

beta

FLOAT

Rotation arond the second axis (in radians).

gamma

FLOAT

Rotation around the third axis (in radians).

xTrans

FLOAT

Translation in the x direction.

yTrans

FLOAT

Translation in the y direction.

zTrans

FLOAT

Translation in the z direction.

origin

CONST_OBJECT Point

Optional origin of rotation if other than (0,0,0).

Return values
Name Type Description

rigidTransform

OBJECT Transform

The new 3D rigid transform

Sample
local rigidTransform = Transform.createRigidEuler3D(rotationOrder, alpha, beta, gamma, xTrans, yTrans, zTrans, origin)
createScaling2D()
Short description

Creates a 2D scaling transform which scales in the x- and y-dimensions.

Parameters
Name Type Description

xScale

FLOAT

Scaling in the x direction

yScale

FLOAT

Optional scaling in the y direction. If omitted the same scaling will be used in both x and y direction.

origin

CONST_OBJECT Point

Optional origin of scaling if other than (0,0)

Return values
Name Type Description

transform

OBJECT Transform

The new 2D scaling transform which is of type SIMILARITY

Sample
local transform = Transform.createScaling2D(xScale, yScale, origin)
createScaling3D()
Short description

Creates a 3D scaling transform which scales in the x-, y-, and z-dimensions.

Parameters
Name Type Description

xScale

FLOAT

Scaling in the x direction

yScale

FLOAT

Optional scaling in the y direction. If omitted the scaling for the x direction will also be used in the y direction.

zScale

FLOAT

Optional scaling in the z direction. If omitted the scaling for the x direction will also be used in the z direction.

origin

CONST_OBJECT Point

Optional origin of scaling if other than (0,0)

Return values
Name Type Description

transform

OBJECT Transform

The new 3D scaling transform which is of type SIMILARITY

Sample
local transform = Transform.createScaling3D(xScale, yScale, zScale, origin)
createSimilarity2D()
Short description

Creates a 2D similarity transform with rotation, scale and translation.

Parameters
Name Type Description

rotation

FLOAT

Counter clockwise rotation (in radians)

scale

FLOAT

Scale factor

xTrans

FLOAT

Translation in the x direction

yTrans

FLOAT

Translation in the y direction

origin

CONST_OBJECT Point

Optional origin of rotation if other than (0,0)

Return values
Name Type Description

similarityTransform

OBJECT Transform

The new 2D similarity transform

Sample
local similarityTransform = Transform.createSimilarity2D(math.pi/2, scale, xTrans, yTrans, origin)
createTranslation2D()
Short description

Creates a 2D translational transform.

Parameters
Name Type Description

xTrans

FLOAT

Translation in the x direction

yTrans

FLOAT

Translation in the y direction

Return values
Name Type Description

transform

OBJECT Transform

The new 2D translational transform

Sample
local transform = Transform.createTranslation2D(xTrans, yTrans)
createTranslation3D()
Short description

Creates a 3D translational transform.

Parameters
Name Type Description

xTrans

FLOAT

Translation in the x direction

yTrans

FLOAT

Translation in the y direction

zTrans

FLOAT

Translation in the z direction

Return values
Name Type Description

transform

OBJECT Transform

The new 3D translational transform

Sample
local transform = Transform.createTranslation3D(xTrans, yTrans, zTrans)
decomposeRigid2D()
Short description

Decomposes a 2D rigid transform into rotation and translation components. The transform must not contain a reflection.

Parameters
Name Type Description

rigidTransform

CONST_OBJECT Transform

The 2D rigid transform.

Return values
Name Type Description

rotation

FLOAT

Counter clockwise rotation (in radians).

xTrans

FLOAT

Translation in the x direction.

yTrans

FLOAT

Translation in the y direction.

Sample
local rotation, xTrans, yTrans = Transform.decomposeRigid2D(rigidTransform)
decomposeRigidEuler3D()
Short description

Decomposes a 3D rigid transform into Euler angles and translation. Rotations are parameterized and applied in the order specified by the rotation order. E.g. to recreate a transformation decomposed using "ZYX" rotation order, first rotate alpha around the world z-axis, then beta around the world y-axis and finally gamma around the world x-axis. All rotations are according to the right hand rule, positive is clockwise when looking along the direction of the rotation axis. The transform must not contain a reflection.

Parameters
Name Type Description

rigidTransform

CONST_OBJECT Transform

The 3D rigid transform.

rotationOrder

ENUM RotationOrder

Order in which to apply rotations and order of the returned rotation parameters.

Return values
Name Type Description

alpha

FLOAT

Rotation around the first axis (in radians).

beta

FLOAT

Rotation arond the second axis (in radians).

gamma

FLOAT

Rotation around the third axis (in radians).

xTrans

FLOAT

Translation in the x direction.

yTrans

FLOAT

Translation in the y direction.

zTrans

FLOAT

Translation in the z direction.

Sample
local alpha, beta, gamma, xTrans, yTrans, zTrans = Transform.decomposeRigidEuler3D(rigidTransform, rotationOrder)
decomposeSimilarity2D()
Short description

Decomposes a similarity transform into a rigid transform and a scale factor. The similarity transform can be reconstructed by first scaling and then applying the rigid transformation.

Parameters
Name Type Description

similarityTransform

CONST_OBJECT Transform

The 2D similarity transform.

Return values
Name Type Description

scale

FLOAT

Scale factor.

rigidTransform

OBJECT Transform

The rigid part of the transform.

Sample
local scale, rigidTransform = Transform.decomposeSimilarity2D(similarityTransform)
decomposeSimilarity3D()
Short description

Decomposes a similarity transform into a rigid transform and a scale factor. The similarity transform can be reconstructed by first scaling and then applying the rigid transformation.

Parameters
Name Type Description

similarityTransform

CONST_OBJECT Transform

The 3D similarity transform.

Return values
Name Type Description

scale

FLOAT

Scale factor.

rigidTransform

OBJECT Transform

The rigid part of the transform.

Sample
local scale, rigidTransform = Transform.decomposeSimilarity3D(similarityTransform)
decomposeTranslation2D()
Short description

Decomposes a 2D translation transform into translation components.

Parameters
Name Type Description

translationTransform

CONST_OBJECT Transform

The 2D translation transform.

Return values
Name Type Description

xTrans

FLOAT

Translation in the x direction.

yTrans

FLOAT

Translation in the y direction.

Sample
local xTrans, yTrans = Transform.decomposeTranslation2D(translationTransform)
decomposeTranslation3D()
Short description

Decomposes a 3D translation transform into translation components.

Parameters
Name Type Description

translationTransform

CONST_OBJECT Transform

The 3D translation transform.

Return values
Name Type Description

xTrans

FLOAT

Translation in the x direction.

yTrans

FLOAT

Translation in the y direction.

zTrans

FLOAT

Translation in the z direction.

Sample
local xTrans, yTrans, zTrans = Transform.decomposeTranslation3D(translationTransform)
getMatrix()
Short description

Returns the transform matrix.

Parameters
Name Type Description

transform

CONST_OBJECT Transform

The instance to use

Return values
Name Type Description

matrix

OBJECT Matrix

The full 3x3 or 4x4 matrix of this transform.

Sample
local matrix = Transform.getMatrix(transform)
getType()
Short description

Returns the transform type

Parameters
Name Type Description

transform

CONST_OBJECT Transform

The transform to check

Return values
Name Type Description

result

ENUM TransformType

The transform type

Sample
            if (Transform.getType(transform)=="IDENTITY") then
              doSomething()
            end
invert()
Short description

Returns the inverse transform.

Parameters
Name Type Description

transform

CONST_OBJECT Transform

The instance to use

Return values
Name Type Description

inversedTransform

OBJECT Transform

The inverse transformation matrix.

Sample
local inversedTransform = Transform.invert(transform)
rotate2D()
Short description

Returns a 2D transform with a counter clockwise rotation appended to the input transform. The rotation center is optional. If not provided, the world origin is used.

Parameters
Name Type Description

inputTransform

CONST_OBJECT Transform

Input 2D transform.

rotationAngle

FLOAT

The rotation angle in radians.

rotationCenter

CONST_OBJECT Point

The rotation center. Default is the origin.

Return values
Name Type Description

outputTransform

OBJECT Transform

The transform with appended rotation.

Sample
outputTransform = Transform.rotate2D(inputTransform, rotationAngle, rotationCenter)
rotateX()
Short description

Returns a 3D transform with a rotation around an axis parallel to the world x-axis appended to the input transform. The rotation center is optional. If not provided, the world origin is used. Positive rotation is according to the right hand rule, clockwise when looking along the direction of the rotation axis.

Parameters
Name Type Description

inputTransform

CONST_OBJECT Transform

Input 3D transform.

rotationAngle

FLOAT

The rotation angle in radians.

rotationCenter

CONST_OBJECT Point

The rotation center. Default is the origin.

Return values
Name Type Description

outputTransform

OBJECT Transform

The transform with appended rotation.

Sample
outputTransform = Transform.rotateX(inputTransform, rotationAngle, rotationCenter)
rotateY()
Short description

Returns a 3D transform with a rotation around an axis parallel to the world y-axis appended to the input transform. The rotation center is optional. If not provided, the world origin is used. Positive rotation is according to the right hand rule, clockwise when looking along the direction of the rotation axis.

Parameters
Name Type Description

inputTransform

CONST_OBJECT Transform

Input 3D transform.

rotationAngle

FLOAT

The rotation angle in radians.

rotationCenter

CONST_OBJECT Point

The rotation center. Default is the origin.

Return values
Name Type Description

outputTransform

OBJECT Transform

The transform with appended rotation.

Sample
outputTransform = Transform.rotateY(inputTransform, rotationAngle, rotationCenter)
rotateZ()
Short description

Returns a 3D transform with a rotation around an axis parallel to the world z-axis appended to the input transform. The rotation center is optional. If not provided, the world origin is used. Positive rotation is according to the right hand rule, clockwise when looking along the direction of the rotation axis.

Parameters
Name Type Description

inputTransform

CONST_OBJECT Transform

Input 3D transform.

rotationAngle

FLOAT

The rotation angle in radians.

rotationCenter

CONST_OBJECT Point

The rotation center. Default is the origin.

Return values
Name Type Description

outputTransform

OBJECT Transform

The transform with appended rotation.

Sample
outputTransform = Transform.rotateZ(inputTransform, rotationAngle, rotationCenter)
scale2D()
Short description

Returns a 2D transform with a scaling appended to the input transform.

Parameters
Name Type Description

inputTransform

CONST_OBJECT Transform

Input 2D transform.

scaleFactor

FLOAT

The scaling factor to apply.

scaleCenter

CONST_OBJECT Point

The scaling center, remains fixed during scaling. Default is the origin.

Return values
Name Type Description

outputTransform

OBJECT Transform

The transform with appended scaling.

Sample
outputTransform = Transform.scale2D(inputTransform, scaleFactor)
scale3D()
Short description

Returns a 3D transform with a scaling appended to the input transform.

Parameters
Name Type Description

inputTransform

CONST_OBJECT Transform

Input 3D transform.

scaleFactor

FLOAT

The scaling factor to apply.

scaleCenter

CONST_OBJECT Point

The scaling center, remains fixed during scaling. Default is the origin.

Return values
Name Type Description

outputTransform

OBJECT Transform

The transform with appended scaling.

Sample
outputTransform = Transform.scale3D(inputTransform, scaleFactor)
to3D()
Short description

Converts a 2D transform to a 3D transform. The created 3D transform applies the 2D transform to the x,y-coordinates and leaves the z-coordinates unchanged. This holds up to affine transformations. For homographies, the final scaling of the points is applied also to the z-coordinate.

See also

Transform.toType

Parameters
Name Type Description

transform2d

CONST_OBJECT Transform

The 2D source transform.

Return values
Name Type Description

transform3d

OBJECT Transform

The corresponding 3D transform. Nil is returned if input is invalid.

Sample
local transform3d Transform.to3D(transform2d)
toString()
Short description

Get a string representation of the transform. The matrix representing the transform is written row-wise.

Parameters
Name Type Description

transform

CONST_OBJECT Transform

Input transform

Return values
Name Type Description

str

STRING

String representation of the transform

Sample
print("The transform is: " .. transform:toString())
toType()
Short description

Returns a copy of the transformation marked as desired type. If the desired type is not general enough to support the actual transformation, nil is returned. The transform itself is not changed. Converting to a more general type always succeeds.

See also

Transform.to3D

Parameters
Name Type Description

transform

CONST_OBJECT Transform

The source transform.

desiredType

ENUM TransformType

The desired transform type, e.g., RIGID, SIMILARITY, AFFINE, TRANSLATION.

Return values
Name Type Description

convertedTransform

OBJECT Transform

The transform of the desired type, or nil if the desired type was not compatible with the actual transform.

Sample
local convertedTransform Transform.toType(transform, "RIGID")
translate2D()
Short description

Returns a 2D transform with a translation in world coordinates appended to the input transform.

Parameters
Name Type Description

inputTransform

CONST_OBJECT Transform

Input 2D transform.

xTrans

FLOAT

The translation along the x-axis.

yTrans

FLOAT

The translation along the y-axis.

Return values
Name Type Description

outputTransform

OBJECT Transform

The transform with appended translation.

Sample
outputTransform = Transform.translate2D(inputTransform, xTrans, yTrans)
translate3D()
Short description

Returns a 3D transform with a translation in world coordinates appended to the input transform.

Parameters
Name Type Description

inputTransform

CONST_OBJECT Transform

Input 3D transform.

xTrans

FLOAT

The translation along the x-axis.

yTrans

FLOAT

The translation along the y-axis.

zTrans

FLOAT

The translation along the z-axis.

Return values
Name Type Description

outputTransform

OBJECT Transform

The transform with appended translation.

Sample
outputTransform = Transform.translate3D(inputTransform, xTrans, yTrans, zTrans)

TriSpector

Short description

TriSpectorP specific functionality.

Functions

getLaserEnabled()
Short description

Returns true if the laser is on.

Return values
Name Type Description

enabled

BOOL

true if the laser is on.

Sample
enabled = TriSpector.getLaserEnabled()
readTriSpector1000Heightmap()
Short description

Read the TriSpector1000 image format (png).

Parameters
Name Type Description

path

STRING

Path to input file

Return values
Name Type Description

heightImage

OBJECT Image

Height map

reflectanceImage

OBJECT Image

Reflectance image

Sample
heightImage, reflectanceImage = TriSpector.readTriSpector1000Heightmap("resources/image.png")
setLaserEnabled()
Short description

Turn laser on or off.

Parameters
Name Type Description

enable

BOOL

true to turn laser on, false to turn it off.

Sample
TriSpector.setLaserEnabled(true)

UDPSocket

Short description

Provides functionality for sending/receiving UDP packets. First a new UDPSocket needs to be created using the create function. Afterwards it could be set to a specified interface using setInterface()-function. Then a call to the bind-function binds the udp socket to a port and transmit calls and OnReceive events are possible. If bind()-function is not called, the socket is bind implicitly to the first transmit target. Data could be transmitted to the server using the "transmit" function. Data could be received by a register to the "OnReceive" event or by calling the blocking receive()-function.

Functions

bind()
Short description

Binds the socket to a specific local port.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the UDP socket

port

INT

The port to bind to

Return values
Name Type Description

success

BOOL

True if socket was bound successfully, false if an error occurred.

Sample
success = UDPSocket.bind(handle, 10000)
create()
Short description

Creates a UDP socket instance.

Return values
Name Type Description

handle

HANDLE

The instance handle of the UDP socket

Sample
handle = UDPSocket.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

receive()
Short description

Receives one UDP packet with a specified timeout. The socket must be bound first either explicitly by calling bind or implicitly by a preceding transmit. If timeout is zero then it directly returns without any return values. Incoming data between multiple receive calls is queued per message. There is a fix receive queue size of 10 packets per default and can be changed using the setReceiveQueueSize()-function. More data is discarded.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the UDP socket

timeout

INT

Timeout in ms to wait for received data. 0 is default and means directly return.

Return values
Name Type Description

data

BINARY

The received data

ipAddress

STRING

The peer address the data was received from

port

INT

The peer port the data was received from

register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

setInterface()
Short description

Sets the interface to bind the socket to.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the UDP socket

ifName

ENUM EthernetInterfaces

One of the available interfaces

Sample
UDPSocket.setInterface(handle, "ETH1")
setReceiveQueueSize()
Short description

Sets the internal queue size for the receive()-function. Default is 10 packets and discarding the oldest item and warn if overrun occurs. Set to 0 to disable the queue and receiving from the receive()-function, which also increases performance if only receiving over OnReceive-event.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the UDP socket

queueSize

INT

The new receive queue size.

bDiscardIfFull

BOOL

Set to true to discard the newest item which is currently added instead of discarding the oldest element. Default is false.

warnOverruns

BOOL

Set to false to disable warning on overruns when using the receive()-function. Default is true.

Sample
UDPSocket.setReceiveQueueSize(handle, 50)
transmit()
Short description

Transmit a UDP packet to the specified peer. This will trigger an implicit bind if the socket has not been bound yet.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the UDP socket

ipAddress

STRING

The ip address to transmit to

port

INT

The port to transmit to

data

BINARY

The data which to be transmitted

Return values
Name Type Description

numberOfBytesTransmitted

INT

Number of bytes transmitted; 0 if transmit failed

Sample
transmitted = UDPSocket.transmit(handle, "192.168.0.1", 10000, "Hello world")

Events

OnReceive
Short description

The event which is triggered when data is received on the socket. The socket must be bound first either explicitly by calling bind or implicitly by a preceding transmit. For each packet receive there is one event thrown.

Parameters
Name Type Description

handle

HANDLE

The instance handle of the UDP socket

data

BINARY

The received data packet

ipAddress

STRING

The peer address the data was received from

port

INT

The peer port the data was received from

View

Short description

Provides view function for iconics like Text, Scan, Image and PointCloud.

Functions

add()
Short description

Adds the iconics, with an optional decoration, to be shown in viewers when View.present is called. If the decoration is omitted a default decoration is used. Iconics are stored by reference, if they are modified between View.add and View.present, only their latest state will be presented. This function is deprecated. Use View.addXYZ instead. Reasons for deprecation: type-safety, missing parent-id leads to usage of wrong coordinate-systems.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

iconics

CONST_AUTO

The iconic or list of iconics to be viewed.

decoration

CONST_OBJECT [API:DataFormat:]

Optional decoration for the iconics.

Sample
View.add(handle, iconics, decoration)
addGraph()
Short description

Adds a graph to be shown in viewers when View.present is called. The graph type, e.g., xy-plot or histogram, is set by the GraphDecoration object. If the parentId refers to an Image, the graph will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

values

FLOAT

A vector of float values to be plotted on the y-axis of the graph.

coordinates

FLOAT

Optional vector of float values for the x-axis, e.g., time, position etc. The default value is an empty vector, in which case the integer indexes of the value vector are used.

decoration

CONST_OBJECT View.GraphDecoration

Optional decoration for the graph.

iconicId

STRING

Optional iconic id.

parentId

STRING

Optional parent id.

Return values
Name Type Description

iconicId

STRING

Iconic id. An id is generated if not provided.

Sample
iconicId = View.addGraph(handle, values, coordinates, decoration, iconicId)
addHeightmap()
Short description

Adds an Image that is shown as a heightmap in viewers when View.present is called. If a list of images is used, the first image will be presented as the heightmap. Consecutive images are used as selectable view-components (textures) for the heightmap using the labels from the labels list argument.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

images

CONST_OBJECT Image

The heightmap to be viewed. Additional images will be used as selectable view components.

decorations

CONST_OBJECT View.ImageDecoration

Optional decorations for the image(s).

labels

STRING

Optional labels for the additional images

iconicId

STRING

Optional iconic id.

parentId

STRING

Optional parent id. The same parent id is used for all added images.

Return values
Name Type Description

iconicId

STRING

Iconic id. An id is generated if not provided.

Sample
iconicId = View.addHeightmap(handle, {heightmap, reflectance}, {reflectanceDecoration}, {"Reflectance"}, "heightmap1")
addImage()
Short description

Adds one or more Image to be shown in viewers when View.present is called.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

image

CONST_OBJECT Image

The image(s) to be viewed.

decoration

CONST_OBJECT View.ImageDecoration

Optional decoration for the image(s).

iconicId

STRING

Optional iconic id(s). One iconic id per image must be supplied if this parameter is used.

parentId

STRING

Optional parent id. The same parent id is used for all added images.

Return values
Name Type Description

iconicId

STRING

A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample
iconicId = View.addImage(handle, image, imageDecoration, "image1")
addMesh()
Short description

Adds one or more Meshes to be shown in viewers when View.present is called.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

mesh

OBJECT Mesh

The mesh(es) to be viewed.

decoration

CONST_OBJECT View.MeshDecoration

Optional decoration for the mesh(es).

iconicId

STRING

Optional iconic id(s). One iconic id per mesh must be supplied if this parameter is used.

parentId

STRING

Optional parent id. The same parent id is used for all added meshes.

Return values
Name Type Description

iconicId

STRING

A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample
iconicId = View.addMesh(handle, mesh, decoration, "mesh1")
addPixelRegion()
Short description

Adds one or more Image.PixelRegion to be shown as an overlay for an iconic or separately when View.present is called. If a parentId is given, the PixelRegion is displayed as a clipped overlay for the given parent, otherwise it is drawn separately in world-coordinates.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

pixelRegion

CONST_OBJECT Image.PixelRegion

The pixel region(s) to be viewed.

decoration

CONST_OBJECT View.PixelRegionDecoration

Optional decoration for the pixel region(s). The same decoration is used for all added pixel regions.

iconicId

STRING

Optional iconic id(s). One iconic id per pixel region must be supplied if this parameter is used.

parentId

STRING

Optional parent id. The same parent id is used for all added pixel regions.

Return values
Name Type Description

iconicId

STRING

A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample
iconicId = View.addPixelRegion(handle, pixelRegion, pixelRegionDecoration, "pixelRegion1", "image1")
addPoint()
Short description

Adds one or more Point objects to be shown in viewers when View.present is called. If the parentId refers to an Image, the point will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

See also

Image.drawPoint

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

point

CONST_OBJECT [API:DataFormat:]

The point(s) which is to be viewed.

decoration

CONST_OBJECT View.ShapeDecoration

Optional decoration for the point. The same decoration is used for all added points. N.B: A ShapeDecoration shall be used, there is no dedicated decoration only for Points.

iconicId

STRING

Optional iconic id(s). One iconic id per point must be supplied if this parameter is used.

parentId

STRING

Optional parent id. The same parent id is used for all added points.

Return values
Name Type Description

iconicId

STRING

A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample
iconicId = View.addPoint(handle, point, shapeDecoration, "point1", "image1")
addPointCloud()
Short description

Adds one or more PointClouds to be shown in viewers when View.present is called.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

pointCloud

CONST_OBJECT PointCloud

The point cloud(s) to be viewed.

decoration

CONST_OBJECT View.PointCloudDecoration

Optional decoration for the point cloud(s).

iconicId

STRING

Optional iconic id(s). One iconic id per point cloud must be supplied if this parameter is used.

parentId

STRING

Optional parent id. The same parent id is used for all added pointClouds.

Return values
Name Type Description

iconicId

STRING

A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample
iconicId = View.addPointCloud(handle, pointCloud, pointCloudDecoration, "pointcloud1")
addProfile()
Short description

Adds one or more profiles to be shown in viewers when View.present is called. The visualization properties are specified using a GraphDecoration object. If the parentId refers to an Image, the profile will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

profile

OBJECT Profile

The profile(s) to be viewed.

decoration

CONST_OBJECT View.GraphDecoration

Optional decoration for the profile.

iconicId

STRING

Optional iconic id(s). One iconic id per profile must be supplied if this parameter is used.

parentId

STRING

Optional parent id. The same parent id is used for all added profiles.

Return values
Name Type Description

iconicId

STRING

A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample
iconicId = View.addProfile(handle, profile, decoration, iconicId)
addShape()
Short description

Adds either one or more Shape/Shape3D objects to be shown in viewers when View.present is called. If the parentId refers to an Image, the shape will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

See also

Image.drawShape

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

shape

CONST_OBJECT [API:DataFormat:]

The shape(s)/point(s) which is to be viewed.

decoration

CONST_OBJECT View.ShapeDecoration

Optional decoration for the shape. The same decoration is used for all added shapes.

iconicId

STRING

Optional iconic id(s). One iconic id per shape must be supplied if this parameter is used.

parentId

STRING

Optional parent id. The same parent id is used for all added shapes.

Return values
Name Type Description

iconicId

STRING

A (vector of) iconic id(s). Id(s) are generated if not provided.

Sample
iconicId = View.addShape(handle, shape, shapeDecoration, "shape1", "image1")
addText()
Short description

Adds a string to be drawn when View.present is called. If the parentId refers to an Image, the text will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.

See also

Image.drawText

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

text

STRING

The text which is to be viewed.

decoration

CONST_OBJECT View.TextDecoration

Optional decoration for the text.

iconicId

STRING

Optional iconic id.

parentId

STRING

Optional parent id.

Return values
Name Type Description

iconicId

STRING

Iconic id. An id is generated if not provided.

Sample
iconicId = View.addText(handle, "Hello world", textDecoration, "text1", "image1")
clear()
Short description

Removes all previously added iconics from viewers when View.present is called.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

Sample
View.clear(handle)
countConnections()
Short description

Returns the number of connected viewers at this viewer’s identifier. If no identifier is set, it counts all connected viewers on all identifiers.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

Return values
Name Type Description

connectedCount

INT

The number of connected viewers or 0 if none is connected.

create()
Short description

Creates a new View.

Parameters
Name Type Description

id

STRING

Optional viewer identifier which is used to select dedicated viewers.

Return values
Name Type Description

handle

HANDLE

The new View

Sample
viewer = View.create()
deregister()
Short description

This function is used to deregister from any registered event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to deregister from

callback

STRING

The function name which was registered on the event

Return values
Name Type Description

success

BOOL

True if successfully deregistered. False if event does not exist or callback wasn’t registered.

installEditor()
Short description

Installs an editor for the specified iconic so that it can be edited in viewers. The editor is available after calling View.present. When an iconic is changed by an editor the View.OnChange event is published.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

iconicId

STRING

ID of the iconic for which to install an editor.

Sample
View.installEditor(handle, "shape1")
present()
Short description

Updates registered viewers with changes to the View. This lets viewers - show iconics added with any of the View.add-functions - make editors (added with View.installEditor) available - remove (View.remove) or clear (View.clear) iconics. The Channel parameter is optional and defaults to LIVE. In overload situations, ASSURED means that present calls will be queued and LIVE means that older present calls will be discarded.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

channel

ENUM Channel

The channel on which to transmit the presented iconics. Default value is LIVE.

Sample
View.present(handle, "LIVE")
rasterize()
Short description

Generates a 2D color image by rasterizing Shapes, Points, PixelRegions and Text as overlays into the pixels of a previously added image. The base image to rasterize into is taken to be the last added image using View.addImage or View.addHeightmap. Any subsequent calls to View.addShape, View.addPoint, View.addPixelRegion, View.addText, View.addPointCloud are used to add overlay graphics into the base image by modifying the pixel values in this image. This results in an image similar to what is shown in the viewer. Note however that this function does not have the full capacity as the external viewer typically has, so there will be differences. The main limitations are as follows: * 3D scenes cannot be reproduced, e.g., 3D pointcloud or mesh visualizations cannot be generated. * The resolution of the generated graphics is limited by the image rasterized into. * For text rendering there is a more limited set of ASCII characters supported compared to the external viewer. Moreover, rotated text is not currently supported. View.rasterize must be called prior to View.present as this latter function clears the internal list of objects inside the viewer instance. For each overlay iconic type there are also restrictions in terms of capacity compared to an external viewer. The support and limitations are as described below. Base image: The base image to draw on is defined to the last call by either by View.addImage or View.addHeightMap. Any pixel type is supported, e.g., UINT8, UINT16, FLOAT32. Grayscale images will be converted to RGB using a colormap. If the image is UINT8 without missing data a grayscale RGB image is generated. Otherwise the colormap 'JET' is used for conversion to RGB. To select a custom color map use the colormap ID in the View.ImageDecoration object when adding the image to the viewer. See details further down. The View.addHeightmap takes both a range image and an intensity image as input. To select which of these images to use there is a channelIndex input parameter to View.rasterize. Overlay support and restrictions: * PixelRegion - Fully supported using the provided decoration object. Full decoration support. * Shape - Supported as rasterized versions without any anti-aliasing. Full decoration support. * Point - Supported as rasterized versions without any anti-aliasing. Full decoration support. * Text - Supported with approximate mapping to the text rendered in the viewer. A limited ASCII-set is supported, i.e., not all characters will be rendered. Not all properties in the TextDecoration object are supported. * PointCloud - Partial support. Points are rendered over their x,y-coordinates in the image. The same colormaps are available as for the Image type. The following iconics are not supported: Mesh, Profile, Graph, Scan The colors for the rasterized image or pointcloud can be selected by the colormap ID in the View.ImageDecoration.setColormap or conversely in the View.PointCloudDecoration.setZColormap functions. This ID is mapped to the View.ColorMap.fromMap enums in the following order: 'AUTUMN', 'BLUE_WHITE_RED', 'COOL', 'GRAY', 'HOT', 'HSV', 'JET', 'RAINBOW', 'SPRING', 'SUMMER', 'THERMAL', 'TRAFFIC_LIGHT', 'WINTER', 'RGB'. Default is zero which attempts to mimic the default viewer behavior. Set 1 to get 'AUTUMN' and -1 to get an inverted 'AUTUMN' colorization.

Keywords

color, jpeg, jpg, png, render, draw

Parameters
Name Type Description

viewer

HANDLE

The viewer instance to rasterize.

channelIndex

INT

Only relevant when View.addHeightMap was used to add the base image. Default is 0, which means that the heightmap/range image is used as base image. Set 1 to use the reflectance/intensity image instead.

Return values
Name Type Description

image

OBJECT Image

Rasterized color RGB image. Nil on failure.

Sample
local image = View.rasterize(viewer)
register()
Short description

This function is used to register for any event of the handle.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

eventname

STRING

The event to register to

callback

STRING

The function name to call on the event occurrence

Return values
Name Type Description

success

BOOL

True if successfully registered. False if event does not exist.

remove()
Short description

Removes the iconic with the given id from viewers when View.present is called.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

iconicId

STRING

Id of the iconic to remove.

Sample
View.remove(handle, iconicId)
setDefaultDecoration()
Short description

Sets a default decoration, e.g., ShapeDecoration or ImageDecoration, that will be used in successive calls to view() and add() if the optional decoration argument is omitted.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

decoration

OBJECT [API:DataFormat:]

Decoration object that will be set as default.

Sample
View.setDefaultDecoration(handle, decoration)
setFillColor()
Short description

Sets the fill color of the default ShapeDecoration. This function is deprecated, please use View.ShapeDecoration.setFillColor instead.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

red

INT

Red

green

INT

Green

blue

INT

Blue

alpha

INT

Alpha

Sample
View.setFillColor(handle, 255, 0, 0, 255)
setID()
Short description

Set the viewer identifier in order to select dedicated viewers.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

id

STRING

The identifier.

Sample
View.setID(handle, "Viewer1")
setLineColor()
Short description

Sets the line color of the default ShapeDecoration. This function is deprecated, please use View.ShapeDecoration.setLineColor instead.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

red

INT

Red

green

INT

Green

blue

INT

Blue

Sample
View.setLineColor(handle, 255, 0, 0)
setLineWidth()
Short description

Set the line width of the default ShapeDecoration. This function is deprecated, please use View.ShapeDecoration.setLineWidth instead.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

width

INT

The line thickness.

Sample
View.setLineWidth(handle, 1)
uninstallEditor()
Short description

Removes the editor from the specified iconic. The editor is removed from viewers after View.present after calling View.present.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

iconicId

STRING

ID of the iconic for which to uninstall an editor.

Sample
View.uninstallEditor(handle, "shape1")
updateCamera()
Short description

Updates the camera settings for the scene when View.present is called.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

camera

OBJECT View.Camera

The camera to set.

Sample
View.updateCamera(handle, cam)
updateDecoration()
Short description

Updates the decoration of an already existing iconic when View.present is called. The type of the decoration must match the iconic.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

id

STRING

The identifier of the iconic.

decoration

OBJECT [API:DataFormat:]

Decoration object that will be used for the update.

Sample
View.updateDecoration(handle, "shape1", decoration)
updateTransform()
Short description

Updates the pose (position, orientation, scaling) with the given transform of an already existing iconic when View.present is called. It is up to the viewer what kind of transformations are valid.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

id

STRING

The identifier.

transform

OBJECT Transform

Transformation applied to the given object.

Sample
View.updateTransform(handle, "shape1", transform)
view()
Short description

Shows the given iconics (e.g. images, results, etc.) in the available viewers. If the decoration is omitted a default decoration is used. This function is deprecated. Use View.addXYZ and View.present instead. Reasons for deprecation: performance issues, type-safety, missing parent-id leads to usage of wrong coordinate-systems.

Parameters
Name Type Description

handle

HANDLE

The instance to be used.

iconics

CONST_AUTO

The iconic or list of iconics to be viewed.

decoration

CONST_OBJECT [API:DataFormat:]

Optional decoration for the iconics.

Sample
View.view(handle, iconics, decoration)

Events

OnChange
Short description

This event is published when an Iconic is modified using an editor in the Viewer. Apps can register to this event to react to the changes, for example to update their representation of the object with the changes from the viewer.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this view

iconicId

STRING

ID of the modified iconic

iconic

OBJECT [API:DataFormat:]

The modified iconic

OnConnect
Short description

This event is published when a Viewer has connected to the View. Apps can register to this event to perform actions in response to the connection.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this view

OnPointer
Short description

This event is published when a user has interacted with a Viewer using the select tool. Apps can register to this event to receive the id of the iconic under the pointer (if any) and the type of action.

Parameters
Name Type Description

handle

HANDLE

Instance handle of this view

iconicId

STRING

The ID of the iconic under the pointer or an empty string if no iconic was hit.

pointerActionType

ENUM PointerActionType

Pointer action type

pointerType

ENUM PointerType

Pointer type

View.Camera

Short description

Camera object that describes camera properties for the scene in the viewer. To be set with View.setCamera().

Functions

create()
Short description

Creates a new View.Camera

Return values
Name Type Description

camera

HANDLE

The new camera

Sample
cam = View.Camera.create()
setPosition()
Short description

Set the position of the camera.

Parameters
Name Type Description

camera

HANDLE

The instance to be used.

posX

FLOAT

X

posY

FLOAT

Y

posZ

FLOAT

Z

Sample
View.Camera.setPosition(cam, 0, -1, 1000)
setTarget()
Short description

Set the target-vector of the camera.

Parameters
Name Type Description

camera

HANDLE

The instance to be used.

posX

FLOAT

X

posY

FLOAT

Y

posZ

FLOAT

Z

Sample
View.Camera.setTarget(cam, 0, 0, 0)
setUp()
Short description

Set the up-vector of the camera.

Parameters
Name Type Description

camera

HANDLE

The instance to be used.

posX

FLOAT

X

posY

FLOAT

Y

posZ

FLOAT

Z

Sample
View.Camera.setUp(cam, 0, 0, 1)

View.ColorMap

Short description

Create a custom LINEAR color gradient in which colors are specified as entries in a vector with RGBA.

Functions

addStop()
Short description

Adds a color stop (value, R, G, B, A) to the ColorMap. If the value for a stop is outside the defined range, the stop is discarded.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

value

FLOAT

Represents a position between 0 and 1 at which a color for the gradient is defined. If the value equals the value of an existing color stop, the existing color stop is replaced.

red

INT

Red value in range (0, 255).

green

INT

Green value in range (0, 255).

blue

INT

Blue value in range (0, 255).

alpha

INT

Alpha/opacity component in range [0-255] (optional).

Sample
View.ColorMap.addStop(handle, 255, 0, 0)
create()
Short description

Create a new ColorMap.

Parameters
Name Type Description

rangeStart

FLOAT

Define the start of the value range. Default is 0.0 (optional).

rangeStop

FLOAT

Define the stop of the value range. Default is 1.0 (optional).

Return values
Name Type Description

handle

HANDLE

The new ColorMap

Sample
handle = View.ColorMap.create()
fromMap()
Short description

Create a gradient with predefined steps. The ColorMap will be cleared before.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

predefinedMap

ENUM PredefinedColorMap

Create a gradient with predefined steps.

Sample
View.ColorMap.fromMap(handle, "RAINBOW")
setType()
Short description

A enum value indicating whether the ColorMap makes DISCRETE color jumps, or smooth LINEAR transition between color stops.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

type

ENUM ColorMapType

ColorMap type

Sample
View.ColorMap.setType(handle, "DISCRETE")
toImage()
Short description

Convert the ColorMap to an image which represents the ColorMap from left to right.

Parameters
Name Type Description

handle

HANDLE

The instance handle to use

width

INT

Width of the image.

height

INT

Height of the image.

Return values
Name Type Description

image

OBJECT Image

The color map as image object.

Sample
image = View.ColorMap.toImage(handle, 100, 200)
toString()
Short description

Get a user-friendly string description of the ColorMap.

Parameters
Name Type Description

handle

CONST_OBJECT View.ColorMap

The ColorMap object.

Return values
Name Type Description

str

STRING

User-friendly description of the ColorMap.

Sample
str = View.ColorMap.toString(handle)

View.GraphDecoration

Short description

Decoration object that describes visualization properties for graphs. For example, the graph type such as xy-plot (LINE) or histogram (BAR) can be set, as well as colors, text labels, size properties etc.

Functions

create()
Short description

Creates a new GraphDecoration object.

Return values
Name Type Description

deco

OBJECT View.GraphDecoration

The new GraphDecoration

Sample
graphDecoration = View.GraphDecoration.create()
setAspectRatio()
Short description

Sets the graphs aspect ratio.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

type

ENUM AspectRatio

The graphs aspect ratio, EQUAL, SQUARE or FIT. Default value is FIT.

Sample
View.GraphDecoration.setAspectRatio(graphDecoration, "FIT")
setAxisColor()
Short description

Sets color of graph axes.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

red

INT

Red value in range [0,255]

green

INT

Green value in range [0,255]

blue

INT

Blue value in range [0,255]

a

INT

Alpha value in range [0,255]. Optional, default value is 255.

Sample
View.GraphDecoration.setAxisColor(graphDecoration, 255, 0, 0, 255)
setAxisVisible()
Short description

Sets whether to show or hide the axes.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

visible

BOOL

True if axis should be visible, default value is true.

Sample
View.GraphDecoration.setAxisVisible(graphDecoration, false)
setAxisWidth()
Short description

Sets the graphs axis line width.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

width

FLOAT

Axis width. The default value is 0, which lets the viewer automatically decide the size..

Sample
View.GraphDecoration.setAxisWidth(graphDecoration, 2.5)
setBackgroundColor()
Short description

Sets background color of the plot.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

red

INT

Red value in range [0,255]

green

INT

Green value in range [0,255]

blue

INT

Blue value in range [0,255]

a

INT

Alpha value in range [0,255]. Optional, default value is 255.

Sample
View.GraphDecoration.setBackgroundColor(graphDecoration, 255, 0, 0, 255)
setBackgroundVisible()
Short description

Sets whether the background should be visible or not.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

visible

BOOL

True if background should be visible, default value is true.

Sample
View.GraphDecoration.setBackgroundVisible(graphDecoration, false)
setDrawSize()
Short description

Sets the graph drawing size depending on the graph type set (size of points or width of lines or width of bars).

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

size

FLOAT

Draw size. The default value is 0, which lets the viewer automatically decide the size.

Sample
View.GraphDecoration.setDrawSize(graphDecoration, 3)
setDynamicSizing()
Short description

Sets whether sizes should be dynamic and therefore independent from the zoom, or should be larger when zoomed in (default). Dynamic sizing also results in a dynamic tick distance, getting finer when zooming.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

dynamicSizing

BOOL

True if sizing should be dynamic instead of fixed, default value is false.

Sample
View.GraphDecoration.setDynamicSizing(graphDecoration, true)
setGraphColor()
Short description

Sets color of the graph lines, dots or bars.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

red

INT

Red value in range [0,255]

green

INT

Green value in range [0,255]

blue

INT

Blue value in range [0,255]

a

INT

Alpha value in range [0,255]. Optional, default value is 255.

Sample
View.GraphDecoration.setGraphColor(graphDecoration, 255, 0, 0, 255)
setGraphType()
Short description

Sets the graph type to draw lines, dots or bars.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

type

ENUM GraphType

The graph type, DOT, LINE or BAR. Default value is LINE.

Sample
View.GraphDecoration.setGraphType(graphDecoration, "BAR")
setGridColor()
Short description

Sets color of the grid lines.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

red

INT

Red value in range [0,255]

green

INT

Green value in range [0,255]

blue

INT

Blue value in range [0,255]

a

INT

Alpha value in range [0,255]. Optional, default value is 255.

Sample
View.GraphDecoration.setGridColor(graphDecoration, 255, 0, 0, 255)
setGridVisible()
Short description

Sets whether to show or hide the grid lines.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

visible

BOOL

True if grid should be visible, default value is true.

Sample
View.GraphDecoration.setGridVisible(graphDecoration, false)
setIndexCoordinates()
Short description

Sets whether to use the index in the value vector as x value or use the supplied coordinate vector.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

indexAsX

BOOL

True if index rather then the coordinate should be used as x value, default value is false.

Sample
View.GraphDecoration.setIndexCoordinates(graphDecoration, true)
setLabelColor()
Short description

Sets color of the text labels.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

red

INT

Red value in range [0,255]

green

INT

Green value in range [0,255]

blue

INT

Blue value in range [0,255]

a

INT

Alpha value in range [0,255]. Optional, default value is 255.

Sample
View.GraphDecoration.setLabelColor(graphDecoration, 255, 0, 0, 255)
setLabelSize()
Short description

Sets the text size of labels on the axes.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

size

FLOAT

Label text size. The default value is 0, which lets the viewer automatically decide the size.

Sample
View.GraphDecoration.setLabelSize(graphDecoration, 3)
setLabels()
Short description

Sets the label text of the x and y axes.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

xLabel

STRING

x-axis text label, empty by default.

yLabel

STRING

y-axis text label, empty by default.

Sample
View.GraphDecoration.setLabels(graphDecoration, "Time [ms]", "Quantity")
setLabelsVisible()
Short description

Sets whether to show or hide the axes labels.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

visible

BOOL

True if labels should be visible, default value is true.

Sample
View.GraphDecoration.setLabelsVisible(graphDecoration, false)
setPolarPlot()
Short description

Sets whether to use a polar or a linear visualization. If a polar visualization is chosen the coordinates of the graph will be used as angle (in radians) and the value as distance.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

polarVisualization

BOOL

True if a polar visualization should be used, default value is false.

Sample
View.GraphDecoration.setPolarPlot(graphDecoration, true)
setTicksVisible()
Short description

Sets whether to show or hide the axes ticks.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

visible

BOOL

True if ticks should be visible, default value is true.

Sample
View.GraphDecoration.setTicksVisible(graphDecoration, false)
setTitle()
Short description

Sets the title text.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

title

STRING

Title of the graph. Empty by default

Sample
View.GraphDecoration.setTitle(graphDecoration, "Value over Time")
setTitleSize()
Short description

Sets the text size of the graph title.

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

size

FLOAT

Title size. The default value is 0, which lets the viewer automatically decide the size.

Sample
View.GraphDecoration.setTitleSize(graphDecoration, 3)
setXBounds()
Short description

Sets the graphs dimensions in x direction if lowerBound < upperBound, otherwise the dimension will be adjusted automatically

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

lowerBound

FLOAT

Lower bound. The default value is 0, which lets the viewer automatically decide the value.

upperBound

FLOAT

Upper bound. The default value is 0, which lets the viewer automatically decide the value.

Sample
View.GraphDecoration.setXBounds(graphDecoration, 0, 250)
setYBounds()
Short description

Sets the graphs dimensions in y direction if lowerBound < upperBound, otherwise the dimension will be adjusted automatically

Parameters
Name Type Description

deco

OBJECT View.GraphDecoration

The instance to be used

lowerBound

FLOAT

Lower bound. The default value is 0, which lets the viewer automatically decide the value.

upperBound

FLOAT

Upper bound. The default value is 0, which lets the viewer automatically decide the value.

Sample
View.GraphDecoration.setYBounds(graphDecoration, -250, 250)
toString()
Short description

Gets a user-friendly string description of the graph decoration.

Parameters
Name Type Description

deco

CONST_OBJECT View.GraphDecoration

The instance to be used

Return values
Name Type Description

str

STRING

User-friendly description of the graph decoration.

Sample
str = View.GraphDecoration.toString(graphDecoration)

View.ImageDecoration

Short description

Decoration object that describes visualization properties for an image.

Functions

create()
Short description

Creates a new ImageDecoration. The default values for the decoration are: - range = [0,255] - colorMapID = 0

Return values
Name Type Description

imageDecorator

OBJECT View.ImageDecoration

The new ImageDecoration

Sample
imageDecoration = View.ImageDecoration.create()
setColormap()
Short description

Sets an integer ID for the color map to use. An image viewer can have a predefined set of color maps to show scalar images false-coded in color for better contrast.

Parameters
Name Type Description

imageDecorator

OBJECT View.ImageDecoration

The instance to be used.

colorMapID

INT

An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample
View.ImageDecoration.setColormap(imageDecorator, 2)
setRange()
Short description

Sets the pixel value range to visualize. For example, if the range [100,500] is set, all pixel values below 100 should be mapped to black and all pixel values above 500 should be mapped to white. Please note that this function has no effect for UINT8 and RGB24 images.

Parameters
Name Type Description

imageDecorator

OBJECT View.ImageDecoration

The instance to be used.

minRange

FLOAT

The lower bound of the range to visualize.

maxRange

FLOAT

The upper bound of the range to visualize.

Sample
View.ImageDecoration.setRange(imageDecorator, 100, 500)
toString()
Short description

Gets a user-friendly string description of the image decoration.

Parameters
Name Type Description

imageDecoration

CONST_OBJECT View.ImageDecoration

The decoration object.

Return values
Name Type Description

str

STRING

User-friendly description of the image decoration.

Sample
str = View.ImageDecoration.toString(imageDecoration)

View.MeshDecoration

Short description

Decoration object that describes visualization properties for a mesh.

Functions

create()
Short description

Create a new MeshDecoration.

Return values
Name Type Description

handle

OBJECT View.MeshDecoration

The new MeshDecoration

Sample
handle = View.MeshDecoration.create()
setSurfaceColor()
Short description

Set the color of the surface. This color is assigned to the ambient and diffuse material properties. Note that the alpha channel is currently unsupported and will have no effect.

Parameters
Name Type Description

handle

OBJECT View.MeshDecoration

The instance to be used.

r

INT

Red value in range (0,255).

g

INT

Green value in range (0,255).

b

INT

Blue value in range (0,255).

a

INT

Alpha value in range (0,255). Currently unused.

Sample
View.MeshDecoration.setSurfaceColor(handle, 0, 100, 0)
setVisibleFaces()
Short description

Set the triangle face to be rendered.

Parameters
Name Type Description

handle

OBJECT View.MeshDecoration

The instance to be used.

visibleFaces

ENUM VisibleFaces

Specifies what face(s) of the triangles to be rendered. By default both faces are rendered.

Sample
View.MeshDecoration.setVisibleFaces(handle, "FRONT_AND_BACK")
toString()
Short description

Get a user-friendly string description of the mesh decoration.

Parameters
Name Type Description

handle

CONST_OBJECT View.MeshDecoration

The decoration object.

Return values
Name Type Description

str

STRING

User-friendly description of the mesh decoration.

Sample
str = View.MeshDecoration.toString(handle)

View.PixelRegionDecoration

Short description

Decoration object that describes visualization properties for a pixel region.

Functions

create()
Short description

Creates a new PixelRegionDecoration.

Return values
Name Type Description

pixelRegionDecorator

OBJECT View.PixelRegionDecoration

The new PixelRegionDecoration

Sample
pixelRegionDecoration = View.PixelRegionDecoration.create()
setColor()
Short description

Sets the pixel region color.

Parameters
Name Type Description

pixelRegionDecorator

OBJECT View.PixelRegionDecoration

The instance to be used.

red

INT

Red value in range [0,255].

green

INT

Green value in range [0,255].

blue

INT

Blue value in range [0,255].

alpha

INT

Optional alpha value in range [0,255].

Sample
View.PixelRegionDecoration.setColor(pixelRegionDecorator, 255, 0, 0, 255)
toString()
Short description

Gets a user-friendly string description of the pixel region decoration.

Parameters
Name Type Description

pixelRegionDecoration

CONST_OBJECT View.PixelRegionDecoration

The decoration object.

Return values
Name Type Description

str

STRING

User-friendly description of the pixel region decoration.

Sample
str = View.PixelRegionDecoration.toString(pixelRegionDecoration)

View.PointCloudDecoration

Short description

Decoration object that describes visualization properties for a point cloud.

Functions

create()
Short description

Create a new PointCloudDecoration.

Return values
Name Type Description

handle

OBJECT View.PointCloudDecoration

The new PointCloudDecoration

Sample
pointCloudDecoration = View.PointCloudDecoration.create()
setIntensityColormap()
Short description

Set an integer ID for the color map to use for the Intensity range (0 = gray scale).

Parameters
Name Type Description

handle

OBJECT View.PointCloudDecoration

The instance to be used.

colorMapID

INT

An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample
View.PointCloudDecoration.setIntensityColormap(handle, 2)
setIntensityRange()
Short description

Set the lower and upper bound of this component.

Parameters
Name Type Description

handle

OBJECT View.PointCloudDecoration

The instance to be used.

minValue

FLOAT

The lower bound of the intensity range to visualize.

maxValue

FLOAT

The upper bound of the intensity range to visualize.

Sample
View.PointCloudDecoration.setIntensityRange(handle, 0.1, 0.9)
setPointSize()
Short description

Set the size of displayed points.

Parameters
Name Type Description

handle

OBJECT View.PointCloudDecoration

The instance to be used.

pointSize

FLOAT

The size of a point

Sample
View.PointCloudDecoration.setPointSize(handle, 2)
setXColormap()
Short description

Set an integer ID for the color map to use for the X range (0 = gray scale).

Parameters
Name Type Description

handle

OBJECT View.PointCloudDecoration

The instance to be used.

colorMapID

INT

An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample
View.PointCloudDecoration.setXColormap(handle, 2)
setXRange()
Short description

Set the lower and upper bound of this component.

Parameters
Name Type Description

handle

OBJECT View.PointCloudDecoration

The instance to be used.

minValue

FLOAT

The lower bound of the x range to visualize.

maxValue

FLOAT

The upper bound of the x range to visualize.

Sample
View.PointCloudDecoration.setXRange(handle, -100, 100)
setYColormap()
Short description

Set an integer ID for the color map to use for the Y range (0 = gray scale).

Parameters
Name Type Description

handle

OBJECT View.PointCloudDecoration

The instance to be used.

colorMapID

INT

An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample
View.PointCloudDecoration.setYColormap(handle, 2)
setYRange()
Short description

Set the lower and upper bound of this component.

Parameters
Name Type Description

handle

OBJECT View.PointCloudDecoration

The instance to be used.

minValue

FLOAT

The lower bound of the y range to visualize.

maxValue

FLOAT

The upper bound of the y range to visualize.

Sample
View.PointCloudDecoration.setYRange(handle, -100, 100)
setZColormap()
Short description

Set an integer ID for the color map to use for the Z range (0 = gray scale).

Parameters
Name Type Description

handle

OBJECT View.PointCloudDecoration

The instance to be used.

colorMapID

INT

An integer ID for the color map to use. The set of color maps available depends on the viewer component.

Sample
View.PointCloudDecoration.setZColormap(handle, 2)
setZRange()
Short description

Set the lower and upper bound of this component.

Parameters
Name Type Description

handle

OBJECT View.PointCloudDecoration

The instance to be used.

minValue

FLOAT

The lower bound of the z range to visualize.

maxValue

FLOAT

The upper bound of the z range to visualize.

Sample
View.PointCloudDecoration.setZRange(handle, -100, 100)
toString()
Short description

Get a user-friendly string description of the point cloud decoration.

Parameters
Name Type Description

handle

CONST_OBJECT View.PointCloudDecoration

The decoration object.

Return values
Name Type Description

str

STRING

User-friendly description of the point cloud decoration.

Sample
str = View.PointCloudDecoration.toString(handle)

View.ShapeDecoration

Short description

Decoration object that describes visualization properties for shapes and points.

Functions

create()
Short description

Creates a new ShapeDecoration. The default values for the decoration are: - lineWidth = 1.0 - lineColor = (0, 0, 0, 255) - fillColor = (0, 0, 0, 0) - pointType = "DOT" - pointSize = 3.0 These values can be changed by using the corresponding functions.

Return values
Name Type Description

deco

OBJECT View.ShapeDecoration

The new ShapeDecoration

Sample
shapeDecoration = View.ShapeDecoration.create()
setFillColor()
Short description

Sets the fill color. It will be used to fill shape iconics.

Parameters
Name Type Description

deco

OBJECT View.ShapeDecoration

The instance to be used.

red

INT

Red

green

INT

Green

blue

INT

Blue

alpha

INT

Alpha

Sample
View.ShapeDecoration.setFillColor(shapeDecoration, 255, 0, 0, 255)
setLineColor()
Short description

Sets the line color. It will be used for line, points and text iconics as well as stroke color for shape iconics.

Parameters
Name Type Description

deco

OBJECT View.ShapeDecoration

The instance to be used.

red

INT

Red

green

INT

Green

blue

INT

Blue

alpha

INT

Alpha

Sample
View.ShapeDecoration.setLineColor(shapeDecoration, 255, 0, 0, 255)
setLineWidth()
Short description

Set the line width.

Parameters
Name Type Description

deco

OBJECT View.ShapeDecoration

The instance to be used.

width

FLOAT

Width

Sample
View.ShapeDecoration.setLineWidth(shapeDecoration, 2.3)
setPointSize()
Short description

Sets the point size for point iconics.

Parameters
Name Type Description

deco

OBJECT View.ShapeDecoration

The instance to be used.

size

FLOAT

Size

Sample
View.ShapeDecoration.setPointSize(shapeDecoration, 3.5)
setPointType()
Short description

Sets the display type for point iconics.

Parameters
Name Type Description

deco

OBJECT View.ShapeDecoration

The instance to be used.

type

ENUM PointType

The point type (DOT or CROSS).

Sample
View.ShapeDecoration.setPointType(shapeDecoration, "CROSS")
toString()
Short description

Gets a user-friendly string description of the shape decoration.

Parameters
Name Type Description

shapeDecoration

CONST_OBJECT View.ShapeDecoration

The decoration object.

Return values
Name Type Description

str

STRING

User-friendly description of the shape decoration.

Sample
str = View.ShapeDecoration.toString(shapeDecoration)

View.TextDecoration

Short description

Decoration object that describes visualization properties for text overlays. Note that a viewer might not support all properties.

Functions

create()
Short description

Creates a new TextDecoration.

Return values
Name Type Description

textDecorator

OBJECT View.TextDecoration

The new TextDecoration

Sample
textDecorator = View.TextDecoration.create()
setBillboardActive()
Short description

Enable billboard mode. Default is off. When active, the text always faces the camera, and setRotation has no effect.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

active

BOOL

Set true to activate billboard.

Sample
View.TextDecoration.setBillboardActive(textDecorator, true)
setBounds()
Short description

Sets the size of the enclosing bounding box. If set, the text is aligned inside these bounds. The box has its origin at position.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

width

INT

The bounds width.

height

INT

The bounds height.

Sample
View.TextDecoration.setBounds(textDecorator, 300, 100)
setColor()
Short description

Sets the text color.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

red

INT

Red value in range [0,255].

green

INT

Green value in range [0,255].

blue

INT

Blue value in range [0,255].

alpha

INT

Optional alpha value in range [0,255].

Sample
View.TextDecoration.setColor(textDecorator, 255, 0, 0, 255)
setFontFamily()
Short description

Sets the font style family of the text, e.g., sans serif, mono-spaced or serif font style. Depending on the platform the viewer runs on, a concrete font is selected within the given font family.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

fontFamily

ENUM FontFamily

Font family (SANSSERIF, MONOSPACE, SERIF). Default is SANSSERIF.

Sample
View.TextDecoration.setFontFamily(textDecorator, "MONOSPACE")
setHorizontalAlignment()
Short description

Sets the horizontal alignment of the text relative to the given text position.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

horizontalAlignment

ENUM HorizontalAlignment

Horizontal alignment (LEFT, CENTER, RIGHT). Default is LEFT.

Sample
View.TextDecoration.setHorizontalAlignment(textDecorator, "CENTER")
setLineSpacing()
Short description

Sets the line spacing in % of the text size.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

lineSpacing

FLOAT

The line spacing factor. The default value is 1.1.

Sample
View.TextDecoration.setLineSpacing(textDecorator, 1.2)
setPosition()
Short description

Sets the text position.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

positionX

FLOAT

The text position x-coordinate.

positionY

FLOAT

The text position y-coordinate.

positionZ

FLOAT

The text position z-coordinate. Optional, only useful if a 3D viewer is used.

Sample
View.TextDecoration.setPosition(textDecorator, 10, 10)
setRotation()
Short description

Sets the text rotation in radians around the given text position and around the given axis.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

rotation

FLOAT

Text rotation in radians. The default value is 0.

axis

FLOAT

A 3d vector which describes the rotation axis. Default is {0,0,-1}.

Sample
View.TextDecoration.setRotation(textDecorator, 1.5708, {0,1,0})
setSize()
Short description

Sets the text font size.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

fontSize

FLOAT

The text font size. The default value is 10.

Sample
View.TextDecoration.setSize(textDecorator, 10)
setVerticalAlignment()
Short description

Sets the vertical alignment of the text relative to the given text position.

Parameters
Name Type Description

textDecorator

OBJECT View.TextDecoration

The instance to be used.

verticalAlignment

ENUM VerticalAlignment

Vertical alignment (BOTTOM, CENTER, TOP). Default is BOTTOM.

Sample
View.TextDecoration.setVerticalAlignment(textDecorator, "CENTER")
toString()
Short description

Gets a human-friendly string description of the text decoration, containing all properties.

Parameters
Name Type Description

textDecoration

CONST_OBJECT View.TextDecoration

The decoration object.

Return values
Name Type Description

str

STRING

User-friendly description of the text decoration.

Sample
str = View.TextDecoration.toString(textDecoration)

Enumerations

B

Buttons

C

Cipher.Certificate.SigningRequest.Format Cipher.Key.Format Command.Client.AccessMode Command.Client.ByteOrder Command.Client.ProtocolType Connector.DigitalIn.DebounceMode Connector.DigitalIn.SignalLogic Connector.DigitalOut.ActivationMode Connector.DigitalOut.DelayedEvents.MeasurementUnit Connector.DigitalOut.DelayedEvents.StatusCode Connector.DigitalOut.PortOutputMode Connector.DigitalOut.SignalLogic Container.ItemTypes

D

DigitalInPorts DigitalLogic.Gate.Affinity DigitalOutPorts

E

Encoder.DecoderCountMode Encoder.DecoderPhases Encoder.Direction EncoderIncrementSources EthernetInterfaces

F

FTPClient.SecurityProtocol FTPClient.TransferMode FieldBus.CreateMode FieldBus.TransmissionMode File.Archive.ZIP.Compression

I

Image.BorderType Image.Calibration.Correction.CoordinateSystem Image.Calibration.Correction.CorrectionCropMode Image.ColorSpace Image.ConcatenationDirection Image.ContrastDifferenceMode Image.DifferenceMode Image.ExtremaType Image.GaussianFilterType Image.ImageType Image.InpaintMethod Image.InterpolationMethod Image.Matching.BackgroundClutterLevel Image.Matching.EdgeMatcherProcessingUnit Image.Matching.PatternMatcher.EdgeSensitivity Image.Matching.PatternVerifier.EdgeSensitivity Image.Matching.PointMatcher.PoseType Image.Matching.PointMatcher.PoseVariability Image.MetricType Image.MissingDataMethod Image.MorphologicalTransform Image.OCR.Halcon.AutoSegmenter.AutoSegmentationParameters Image.OCR.Halcon.FontClassifier.PreTrainedFonts Image.OCR.Halcon.ManualSegmenter.ManualSegmentationParameters Image.OutputGrid Image.PixelRegion.Filter.FeatureType Image.ProcessingDimension Image.Provider.Camera.V3TConfig2D.ImageTriggerMode Image.Provider.Camera.V3TConfig3D.ImageTriggerDelayUnit Image.Provider.Camera.V3TConfig3D.ImageTriggerMode Image.Provider.Camera.V3TConfig3D.PeakSelectionMode Image.Provider.Camera.V3TConfig3D.ProfileTriggerMode Image.Pyramid.DownsamplingMethod Image.Pyramid.ProcessingUnit Image.ShapeFitter.EdgeSelection IncrementPortConnectors

L

LEDs LUA.math.Constants LUA.utf8.Constants Log.Level

M

MachineLearning.DataSet.LabelType MachineLearning.KMeansClustering.InitMethod MachineLearning.NeuralNet.ActivationFunction MachineLearning.SupportVectorMachine.KernelType Monitor.App.AppStatus MountedDrives

N

NTPClient.TimeSource

O

OPCUA.AccessLevel OPCUA.DataType OPCUA.EventSeverity OPCUA.NodeClass OPCUA.NodeIDType OPCUA.NodeType OPCUA.ReferenceType OPCUA.Server.SecurityConfiguration.MessageSecurityMode OPCUA.Server.SecurityConfiguration.SecurityPolicy OPCUA.Server.SecurityConfiguration.UserTokenPolicy OPCUA.Server.Value.OptionalFieldState OPCUA.Server.Value.UnionField Object.DataFormat

P

Point.NormType PointCloud.ColorMode PointCloud.Matching.Halcon.SurfaceMatcher.NormalComputationMethod PointCloud.toImageMode Profile.AggregateOperation Profile.ContrastDifferenceMode Profile.CoordinateType Profile.Curve.CurveType Profile.CurveFitter.CurveFitMode Profile.CurveFitter.CurveOutlierMarginType Profile.DifferenceMode Profile.DifferentiationOrder Profile.EdgeSide Profile.ExtremaType Profile.FillInvalidMethod Profile.ImageType Profile.Matching.PatternMatcher.ComparisonMode Profile.NoiseType Profile.SlopePolarity Profile.SortKey

S

Script.Priority Script.Queue.Priority SerialComTypes SerialPorts Shape.OutlierMarginType Shape.PointFitMode Shape.ShapeType Shape3D.Shape3DType Shape3D.ShapePointFitMode Statistics.HistogramCompareMethod

T

Transform.RotationOrder Transform.TransformType TriSpector.DeviceVariant

V

View.Channel View.ColorMap.ColorMapType View.ColorMap.PredefinedColorMap View.GraphDecoration.AspectRatio View.GraphDecoration.GraphType View.MeshDecoration.VisibleFaces View.PointerActionType View.PointerType View.Present.Add.IconicType View.Present.Editor.EditorType View.Present.LogLevel View.ShapeDecoration.PointType View.TextDecoration.FontFamily View.TextDecoration.HorizontalAlignment View.TextDecoration.VerticalAlignment

Buttons

Cipher.Certificate.SigningRequest.Format

Items
Value Name Description
PEM

PKCS#10 PEM format

Cipher.Key.Format

Items
Value Name Description
PEM

PEM format. PKI X.509 PEM format for public key, PKCS#8 PEM format for private key.

Command.Client.AccessMode

Items
Value Name Description
BY_NAME

By name (Default)

BY_INDEX

By index

Command.Client.ByteOrder

Items
Value Name Description
BIG_ENDIAN

Big-endian (Default)

LITTLE_ENDIAN

Little-endian

Command.Client.ProtocolType

Items
Value Name Description
COLA_A

CoLa A (Default)

COLA_B

CoLa B

COLA_2

CoLa 2

Connector.DigitalIn.DebounceMode

Items
Value Name Description
TIME_MS

Time in ms

Time based with milliseconds value

INCREMENT_TICK

Increment in ticks

Increment based with ticks as value

Connector.DigitalIn.SignalLogic

Items
Value Name Description
ACTIVE_HIGH

Active high

Active high signal logic is used

ACTIVE_LOW

Active low

Active low signal logic is used

Connector.DigitalOut.ActivationMode

Items
Value Name Description
TIME_MS

Time in ms

Time based with milliseconds value

INCREMENT_TICK

Increment in ticks

Increment based with ticks as value

Connector.DigitalOut.DelayedEvents.MeasurementUnit

Items
Value Name Description
INCREMENT_TICK

Increment in ticks

Value in encoder ticks

TIME_US

Time in us

Value in microseconds

Connector.DigitalOut.DelayedEvents.StatusCode

Items
Value Name Description
OK

OK

The function executed correctly

QUEUE_NOT_ENABLED

Queue not enabled

You have to run Connector.DigitalOut.DelayedEvents.enable before adding a new event

QUEUE_FULL

Queue full

The queue is full

LATE_EVENT

Late event

The added event has already passed

UNORDERED_QUEUE

Unordered queue

The added event does not occur after the last event in the queue

ILLEGAL_DURATION

Illegal duration

Illegal duration value specified

Connector.DigitalOut.PortOutputMode

Items
Value Name Description
HIGH_SIDE

High-side

Digital port works as high-side (PNP) output

LOW_SIDE

Low-side

Digital port works as low-side (NPN) output

PUSH_PULL

Push-pull

Digital port works as push-pull output

Connector.DigitalOut.SignalLogic

Items
Value Name Description
ACTIVE_HIGH

Active high

Active high signal logic is used

ACTIVE_LOW

Active low

Active low signal logic is used

Container.ItemTypes

The different types of which one item in the container can be. Matches the existing framework types.

Items
Value Name Description
OBJECT

object

Only non-const object

CONST_OBJECT

const object

Matches also non-const objects

FLOAT

float

INT

integer

BOOL

bool

STRING

string

BINARY

binary

DigitalInPorts

Items
Value Name Description
DI1

Digital In 1

DI2

Digital In 2

DI3

Digital In 3

DI4

Digital Input 4

Programmable IO 4

DI5

Digital Input 5

Programmable IO 5

DI6

Digital Input 6

Programmable IO 6

DI7

Digital Input 7

Programmable IO 7

DigitalLogic.Gate.Affinity

Items
Value Name Description
SW

Bound to software

HW

Bound to hardware

DigitalOutPorts

Items
Value Name Description
DO4

Digital Output 4

Programmable IO 4

DO5

Digital Output 5

Programmable IO 5

DO6

Digital Output 6

Programmable IO 6

DO7

Digital Output 7

Programmable IO 7

Encoder.DecoderCountMode

Items
Value Name Description
BIDIRECTIONAL

Bidirectional

Counts up in Encoder forward / backward direction

POSITIVE_MOVEMENT

Positive Movement

Counts up in Encoder forward direction / counts down in Encoder backward direction

NEGATIVE_MOVEMENT

Negative Movement

Counts down in Encoder forward direction / counts up in Encoder backward direction

FORWARD_MOVEMENT

Forward Movement

Counts up in Encoder forward direction / no count in Encoder backward direction

BACKWARD_MOVEMENT

Backward Movement

No count in Encoder forward direction / counts up in Encoder backward direction

Encoder.DecoderPhases

Items
Value Name Description
SINGLE_PHASE

Single Phase

DUAL_PHASE

Dual Phase

Encoder.Direction

Items
Value Name Description
FORWARD

Forward Direction

BACKWARD

Backward Direction

EncoderIncrementSources

Items
Value Name Description
ENC1

ENC1

EthernetInterfaces

Items
Value Name Description
ETH1

Ethernet

The only available ethernet interface.

FTPClient.SecurityProtocol

Items
Value Name Description
NONE

None

Plain FTP (no transport security)

FTPS_EXPLICIT

FTPS explicit mode

Require explicit FTP over TLS. Explicit mode: A plain FTP connection is established first, the client then requests to switch to TLS using the FTP command AUTH. This is the usual way to run FTPS.

FTPS_IMPLICIT

FTPS implicit mode

Require implicit FTP over TLS. Implicit mode: A TLS session is established directly, without a previous negotiation via plain FTP. This is a more rare way to run FTPS.

FTPClient.TransferMode

Items
Value Name Description
ASCII

ASCII mode

BINARY

Binary mode

FieldBus.CreateMode

Items
Value Name Description
EXPLICIT_OPEN

Explicit Open

Only create the handle, but do not automatically open communication. Communication must be started explicitly using the function open.

AUTOMATIC_OPEN

Automatic Open

Create the handle and automatically open the communication

FieldBus.TransmissionMode

Items
Value Name Description
CONFIRMED_MESSAGING

Confirmed Messaging

Transmission mode using the SICK Confirmed Messaging protocol to transfer and fragment process data

RAW

Raw

Transmission mode without any protocol

File.Archive.ZIP.Compression

Items
Value Name Description
STORE

Store only, no compression

FAST

Fastest compression

DEFAULT

Default compression

BEST

Best compression, slowest

Image.BorderType

Items
Value Name Description
CONSTANT

CONSTANT

Example: iiii abcdef iiii

REPLICATE

REPLICATE

Example: aaaa abcdef ffff

REFLECT

REFLECT

Example: dcba abcdef fedc

WRAP

WRAP

Example: cdef abcdef abcd

Image.Calibration.Correction.CoordinateSystem

Items
Value Name Description
CAMERA_PIXEL

camera_pixel

Pixel coordinates of the input camera image.

CORRECTED_PIXEL

corrected_pixel

Pixel coordinates of the corrected output image.

CORRECTED_WORLD

corrected_world

Image world coordinates of the corrected output image.

EXTERNAL_WORLD

external_world

Point on the world ground plane (at z=0) as defined by the camera model, usually from a calibration pattern.

Image.Calibration.Correction.CorrectionCropMode

Items
Value Name Description
FULL

full

Full mode, creates an output containing all valid pixels and some zero-valued pixels where the corrected image is undefined.

VALID

valid

Valid mode, creates an output containing only valid pixels, cropping out some values to create a rectangular output image.

Image.ColorSpace

Items
Value Name Description
COLORSPACE_RGB

RGB

RGB color space

COLORSPACE_HSV

HSV

HSV color space

COLORSPACE_LAB

LAB

LAB color space

Image.ConcatenationDirection

Items
Value Name Description
ABOVE

ABOVE

Concatenate image2 above image1

BELOW

BELOW

Concatenate image2 below image1

LEFT

LEFT

Concatenate image2 to the left of image1

RIGHT

RIGHT

Concatenate image2 to the right of image1

Image.ContrastDifferenceMode

Items
Value Name Description
ONE

one

At least one point in the neighborhood should have the specified value margin to the extremal point.

Image.DifferenceMode

Items
Value Name Description
ABS

ABS

Absolute difference.

SQUARE

SQUARE

Squared difference.

Image.ExtremaType

Items
Value Name Description
MAX

MAX

Local maxima

MIN

MIN

Local minima

Image.GaussianFilterType

Items
Value Name Description
SIZE_SELECT

SIZE_SELECT

Choose implementation depending on filter size, default.

TRUNCATED

TRUNCATED

Use convolution with a truncated kernel, this is faster for small filter sizes.

RECURSIVE

RECURSIVE

Use a recursive filter to approximate the kernel. The run-time is independent of filter size and is recommended for large filter sizes.

Image.ImageType

Items
Value Name Description
INT8

int8

signed 8-bit integer

INT16

int16

signed 16-bit integer

INT32

int32

signed 32-bit integer

INT64

int64

signed 64-bit integer

UINT8

uint8

unsigned 8-bit integer

UINT16

uint16

unsigned 16-bit integer

UINT32

uint32

unsigned 32-bit integer

UINT64

uint64

unsigned 64-bit integer

FLOAT32

float32

32-bit floating-point

FLOAT64

float64

64-bit floating-point

RGB24

RGB24

24-bit RGB color image (stored in BGR byte order)

Image.InpaintMethod

Items
Value Name Description
NAVIER_STOKES

NAVIER-STOKES

Navier-Stokes equations based inpainting method.

ALEXANDRU_TELEA

ALEXANDRU TELEA

An Image Inpainting Technique Based on the Fast Marching Method.

Image.InterpolationMethod

Items
Value Name Description
NEAREST

nearest

Resample using a nearest-neighbor interpolation

LINEAR

linear

Resample using 2x2 bilinear interpolation

Image.Matching.BackgroundClutterLevel

Items
Value Name Description
LOW

low

Very few edges not belonging to the object.

MEDIUM

medium

Some edges in the background not belonging to the object.

HIGH

high

Many edges in the background not belonging to the object.

Image.Matching.EdgeMatcherProcessingUnit

Items
Value Name Description
CPU

CPU

Calculations will be done on the CPU.

FPGA

FPGA

The FPGA will be used for hardware acceleration.

Image.Matching.PatternMatcher.EdgeSensitivity

Items
Value Name Description
HIGH

High

All pixels contribute to the verification.

LOW

Low

Pixels close to edges are excluded.

Image.Matching.PatternVerifier.EdgeSensitivity

Items
Value Name Description
HIGH

High

All pixels contribute to the verification.

LOW

Low

Pixels close to edges are excluded.

Image.Matching.PointMatcher.PoseType

Items
Value Name Description
RIGID

Rigid

Searches for objects whose image appears translated and rotated. The scale range is ignored in this mode.

SIMILARITY

Similarity

Searches for objects whose image appears translated, rotated and uniformly scaled.

AFFINE

Affine

Searches for objects whose image appears translated, rotated, non-uniformly scaled and skewed.

HOMOGRAPHY

Homography

This is the most general transform, it allows e.g. out-of-plane rotation for flat objects.

Image.Matching.PointMatcher.PoseVariability

Items
Value Name Description
HIGH

HIGH

High pose variability: larger scale changes and visible perspective effects.

LOW

LOW

Low pose variability: scale changes up to 30% and only small perspective effects.

Image.MetricType

Items
Value Name Description
ABS

ABS

Compute as L1 norm

MAGNITUDE

MAGNITUDE

Compute as L2 norm

Image.MissingDataMethod

Items
Value Name Description
MAX

MAX

Setting missing data pixels to the maximum valid value in the neighborhood.

MIN

MIN

Setting missing data pixels to the minimum valid value in the neighborhood.

MEAN

MEAN

Setting missing data pixels to the mean of all valid values in the neighborhood.

MEDIAN

MEDIAN

Setting missing data pixels to the median of all valid values in the neighborhood.

EDGE

EDGE

Removing missing data by interpolating neighbor pixels in an edge-preserving way.

Image.MorphologicalTransform

Items
Value Name Description
ERODE

ERODE

Morphological erosion.

DILATE

DILATE

Morphological dilation.

OPEN

OPEN

Morphological opening

CLOSE

CLOSE

Morphological closure

GRADIENT

GRADIENT

Morphological gradient

TOPHAT

TOPHAT

Morphological tophat

BLACKHAT

BLACKHAT

Morphological blackhat

Image.OCR.Halcon.AutoSegmenter.AutoSegmentationParameters

Items
Value Name Description
MIN_CONTRAST

min_contrast

The minimal contrast the characters have to their surrounding background.List of values: integer or float value between 1 and 255 for byte images and between 1 and 65.535 for uint2 images. Default value: 15

POLARITY

polarity

'dark_on_light' if the text to be segmented is darker than its background, 'light_on_dark' if the text to be segmented is lighter than its background, and 'both' if both kinds of text are to be segmented. List of values: 'dark_on_light', 'light_on_dark' or 'both'. Default value: 'both'

MIN_CHAR_HEIGHT

min_char_height

The minimal height of the characters in pixels. If text of arbitrary height is to be segmented, 'auto' may be passed. Note that 'min_char_height' refers to characters only. The height of punctuation marks or separators is not restricted by 'min_char_height'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'

MAX_CHAR_HEIGHT

max_char_height

The maximal height of the characters in pixels. If text of arbitrary height is to be segmented, 'auto' may be passed. Note that 'max_char_height' refers to characters only. The height of punctuation marks or separators is not restricted by 'max_char_height'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'

MIN_CHAR_WIDTH

min_char_width

The minimal width of the characters in pixels. If text of arbitrary width is to be segmented, 'auto' may be passed. Note that 'min_char_width' refers to characters only. The width of punctuation marks or separators is not restricted by 'min_char_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'

MAX_CHAR_WIDTH

max_char_width

The maximal width of the characters in pixels. If text of arbitrary width is to be segmented, 'auto' may be passed. Note that 'max_char_width' refers to characters only. The width of punctuation marks or separators is not restricted by 'max_char_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'

MIN_STROKE_WIDTH

min_stroke_width

The minimal stroke width of the characters in pixels. If the minimal stroke width is to be estimated within the text segmentation process automatically, 'auto' may be passed. Note that 'min_stroke_width' refers to characters only. The stroke width of punctuation marks or separators is not restricted by 'min_stroke_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'

MAX_STROKE_WIDTH

max_stroke_width

The maximal stroke width of the characters in pixels. If the maximal stroke width is to be estimated within the text segmentation process automatically, 'auto' may be passed. Note that 'max_stroke_width' refers to characters only. The stroke width of punctuation marks or separators is not restricted by 'max_stroke_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto'

ELIMINATE_BORDER_BLOBS

eliminate_border_blobs

'true' if regions that are touching the border of the image domain should be discarded, otherwise 'false'.List of values: 'true','false'. Default value: 'false'

RETURN_PUNCTUATION

return_punctuation

'true' if small punctuation marks that lie close to the base line of the corresponding text line (e.g. dots or commas) are to be returned. 'false' if no such punctuations should be returned.List of values: 'true','false'. Default value: 'true'

RETURN_SEPARATORS

return_separators

'true' if separators such as a minus or the equality sign should be returned as well. 'false' if no separators should be returned.List of values: 'true','false'. Default value: 'true'

ADD_FRAGMENTS

add_fragments

'true' if fragments, such as the dot on the 'i', should be added to the segmented characters, otherwise 'false'. Be aware, that this can cause noise to be added to the segmented characters.List of values: 'true','false'. Default value: 'true'

TEXT_LINE_STRUCTURE

text_line_structure

To simplify the search for specific structures (e.g. dates or serial numbers) within the segmented text, it is possible to define text line structures. For each text line the distances between the characters are calculated, and based on these distances, the text line is divided into text blocks. Short characters such as '.', '_' and '-' are ignored in this process and treated as spaces. Furthermore, it is possible to define user specific separators which are also ignored. See the description of 'text_line_separators' for details. The text line structure is a string that contains the number of characters for every character block and spaces between these character blocks. For example, if the text to be found is a date with two characters for month, day, and year the structure would be '2 2 2'. If the year may consist of two or four characters, the structure would be '2 2 2-4', indicating that the last character block consists of two to four characters. It is possible to provide up to five structures to match by appending an index to the parameter name, e.g. 'text_line_structure_0', 'text_line_structure_1', etc. If 'text_line_structure' is set to an empty string '', the text to be found may have any structure. Please observe, that every text line structure which is found, is saved as in the text result even if they overlap. If the whole text line containing the text line structure is to be returned instead, it is possible to set 'return_whole_line' accordingly. Default value: ''

TEXT_LINE_SEPARATORS

text_line_separators

A string containing the list of characters which are to be ignored in the process of finding text line structures, see 'text_line_structure' for further details. Please note, user specific separators need to be valid characters within the used OCR classifier. For example, if ':' and '\' are to be ignored, ':\\' should be passed. Please observe, that '\' escapes any special symbol to treat it as a literal, and hence '\\' needs to be passed to use '\' as a separator.List of values: '/', ':', ':\\', '\\/:', etc. Default value: ' '

RETURN_WHOLE_LINE

return_whole_line

'false' if only the segmented text line structures are to be returned as text lines. 'true' if each whole text line containing a text line structure is to be returned in text lines.List of values: 'true','false'. Default value: 'false'

MLP_CLASSIFIER

mlp_classifier

The pre-trained font classifier used within findText for text segmentation. Default value: 'Industrial_Rej.omc'

Image.OCR.Halcon.FontClassifier.PreTrainedFonts

Items
Value Name Description
DOCUMENT_0_9A_Z_NOREJ

Document_0-9A-Z_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

DOCUMENT_0_9A_Z_REJ

Document_0-9A-Z_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

DOCUMENT_0_9_NOREJ

Document_0-9_NoRej.omc

Pre-trained font classifier for symbols: 0-9

DOCUMENT_0_9_REJ

Document_0-9_Rej.omc

Pre-trained font classifier for symbols: 0-9

DOCUMENT_A_ZPLUS_NOREJ

Document_A-Z+_NoRej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥

DOCUMENT_A_ZPLUS_REJ

Document_A-Z+_Rej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥

DOCUMENT_NOREJ

Document_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥

DOCUMENT_REJ

Document_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥

DOTPRINT

DotPrint.omc

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . * :

DOTPRINT_0_9PLUS

DotPrint_0-9+.omc

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . * :

DOTPRINT_0_9PLUS_NOREJ

DotPrint_0-9+_NoRej.omc

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . * :

DOTPRINT_0_9PLUS_REJ

DotPrint_0-9+_Rej.omc

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . * :

DOTPRINT_0_9

DotPrint_0-9.omc

Pre-trained font classifier for symbols: 0-9

DOTPRINT_0_9A_Z

DotPrint_0-9A-Z.omc

Pre-trained font classifier for symbols: 0-9, A-Z

DOTPRINT_0_9A_Z_NOREJ

DotPrint_0-9A-Z_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

DOTPRINT_0_9A_Z_REJ

DotPrint_0-9A-Z_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

DOTPRINT_0_9_NOREJ

DotPrint_0-9_NoRej.omc

Pre-trained font classifier for symbols: 0-9

DOTPRINT_0_9_REJ

DotPrint_0-9_Rej.omc

Pre-trained font classifier for symbols: 0-9

DOTPRINT_A_ZPLUS

DotPrint_A-Z+.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / . * :

DOTPRINT_A_ZPLUS_NOREJ

DotPrint_A-Z+_NoRej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / . * :

DOTPRINT_A_ZPLUS_REJ

DotPrint_A-Z+_Rej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / . * :

DOTPRINT_NOREJ

DotPrint_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . * :

DOTPRINT_REJ

DotPrint_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . * :

HANDWRITTEN_0_9

HandWritten_0-9.omc

Pre-trained font classifier for symbols: 0-9

HANDWRITTEN_0_9_NOREJ

HandWritten_0-9_NoRej.omc

Pre-trained font classifier for symbols: 0-9

HANDWRITTEN_0_9_REJ

HandWritten_0-9_Rej.omc

Pre-trained font classifier for symbols: 0-9

INDUSTRIAL_0_9PLUS_NOREJ

Industrial_0-9+_NoRej.omc

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / + . $ % * e £ ¥

INDUSTRIAL_0_9PLUS_REJ

Industrial_0-9+_Rej.omc

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / + . $ % * e £ ¥

INDUSTRIAL_0_9A_Z_NOREJ

Industrial_0-9A-Z_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

INDUSTRIAL_0_9A_Z_REJ

Industrial_0-9A-Z_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

INDUSTRIAL_0_9_NOREJ

Industrial_0-9_NoRej.omc

Pre-trained font classifier for symbols: 0-9

INDUSTRIAL_0_9_REJ

Industrial_0-9_Rej.omc

Pre-trained font classifier for symbols: 0-9

INDUSTRIAL_A_ZPLUS_NOREJ

Industrial_A-Z+_NoRej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / + . $ % * e £ ¥

INDUSTRIAL_A_ZPLUS_REJ

Industrial_A-Z+_Rej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / + . $ % * e £ ¥

INDUSTRIAL_NOREJ

Industrial_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / + . $ % * e £ ¥

INDUSTRIAL_REJ

Industrial_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / + . $ % * e £ ¥

MICR

MICR.omc

Pre-trained font classifier.

OCRA

OCRA.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRA_0_9

OCRA_0-9.omc

Pre-trained font classifier for symbols: 0-9

OCRA_0_9A_Z

OCRA_0-9A-Z.omc

Pre-trained font classifier for symbols: 0-9, A-Z

OCRA_0_9A_Z_NOREJ

OCRA_0-9A-Z_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

OCRA_0_9A_Z_REJ

OCRA_0-9A-Z_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

OCRA_0_9_NOREJ

OCRA_0-9_NoRej.omc

Pre-trained font classifier for symbols: 0-9

OCRA_0_9_REJ

OCRA_0-9_Rej.omc

Pre-trained font classifier for symbols: 0-9

OCRA_A_ZPLUS

OCRA_A-Z+.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRA_A_ZPLUS_NOREJ

OCRA_A-Z+_NoRej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRA_A_ZPLUS_REJ

OCRA_A-Z+_Rej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRA_NOREJ

OCRA_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRA_REJ

OCRA_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRB

OCRB.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRB_0_9

OCRB_0-9.omc

Pre-trained font classifier for symbols: 0-9

OCRB_0_9A_Z

OCRB_0-9A-Z.omc

Pre-trained font classifier for symbols: 0-9, A-Z

OCRB_0_9A_Z_NOREJ

OCRB_0-9A-Z_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

OCRB_0_9A_Z_REJ

OCRB_0-9A-Z_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

OCRB_0_9_NOREJ

OCRB_0-9_NoRej.omc

Pre-trained font classifier for symbols: 0-9

OCRB_0_9_REJ

OCRB_0-9_Rej.omc

Pre-trained font classifier for symbols: 0-9

OCRB_A_ZPLUS

OCRB_A-Z+.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRB_A_ZPLUS_NOREJ

OCRB_A-Z+_NoRej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRB_A_ZPLUS_REJ

OCRB_A-Z+_Rej.omc

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRB_NOREJ

OCRB_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

OCRB_PASSPORT

OCRB_passport.omc

Pre-trained font classifier for symbols: 0-9, A-Z, + and <

OCRB_PASSPORT_NOREJ

OCRB_passport_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, + and <

OCRB_PASSPORT_REJ

OCRB_passport_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, + and <

OCRB_REJ

OCRB_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥

PHARMA

Pharma.omc

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . ( ) :

PHARMA_0_9PLUS

Pharma_0-9+.omc

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . ( ) :

PHARMA_0_9PLUS_NOREJ

Pharma_0-9+_NoRej.omc

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . ( ) :

PHARMA_0_9PLUS_REJ

Pharma_0-9+_Rej.omc

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . ( ) :

PHARMA_0_9

Pharma_0-9.omc

Pre-trained font classifier for symbols: 0-9

PHARMA_0_9A_Z

Pharma_0-9A-Z.omc

Pre-trained font classifier for symbols: 0-9, A-Z

PHARMA_0_9A_Z_NOREJ

Pharma_0-9A-Z_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

PHARMA_0_9A_Z_REJ

Pharma_0-9A-Z_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z

PHARMA_0_9_NOREJ

Pharma_0-9_NoRej.omc

Pre-trained font classifier for symbols: 0-9

PHARMA_0_9_REJ

Pharma_0-9_Rej.omc

Pre-trained font classifier for symbols: 0-9

PHARMA_NOREJ

Pharma_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . ( ) :

PHARMA_REJ

Pharma_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . ( ) :

SEMI

SEMI.omc

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - .

SEMI_NOREJ

SEMI_NoRej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - .

SEMI_REJ

SEMI_Rej.omc

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - .

UNIVERSAL_0_9_NOREJ

Universal_0-9_NoRej.occ

Pre-trained font classifier for symbols: 0-9

UNIVERSAL_0_9_REJ

Universal_0-9_Rej.occ

Pre-trained font classifier for symbols: 0-9

UNIVERSAL_0_9PLUS_NOREJ

Universal_0-9+_NoRej.occ

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥

UNIVERSAL_0_9PLUS_REJ

Universal_0-9+_Rej.occ

Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥

UNIVERSAL_0_9A_Z_NOREJ

Universal_0-9A-Z_NoRej.occ

Pre-trained font classifier for symbols: 0-9, A-Z

UNIVERSAL_0_9A_Z_REJ

Universal_0-9A-Z_Rej.occ

Pre-trained font classifier for symbols: 0-9, A-Z

UNIVERSAL_0_9A_ZPLUS_NOREJ

Universal_0-9A-Z+_NoRej.occ

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥

UNIVERSAL_0_9A_ZPLUS_REJ

Universal_0-9A-Z+_Rej.occ

Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥

UNIVERSAL_A_ZPLUS_NOREJ

Universal_A-Z+_NoRej.occ

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥

UNIVERSAL_A_ZPLUS_REJ

Universal_A-Z+_Rej.occ

Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥

UNIVERSAL_NOREJ

Universal_NoRej.occ

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥

UNIVERSAL_REJ

Universal_Rej.occ

Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥

Image.OCR.Halcon.ManualSegmenter.ManualSegmentationParameters

Items
Value Name Description
CHAR_HEIGHT

char_height

Height of the characters in pixels. Refers to an uppercase character. List of values: integer or float value greater than or equal to 1. Default value: 30px

CHAR_WIDTH

char_width

Width of the characters in pixels. Refers to an uppercase character. List of values: integer or float value greater than or equal to 1. Default value: 20px

STROKE_WIDTH

stroke_width

Stroke width of the characters in pixels. List of values: integer or float value greater than or equal to 0. Default value: 4.0px

BASE_LINE_TOLERANCE

base_line_tolerance

Maximum base line deviation of the characters (in percent of 'char_height'). Default value: 0.15

POLARITY

polarity

'dark_on_light' if the text to be segmented is darker than its background, otherwise 'light_on_dark'. List of values: 'dark_on_light' or 'light_on_dark'. Default value: 'dark_on_light'

UPPERCASE_ONLY

uppercase_only

'true' if the text to be segmented contains uppercase characters or numbers only, otherwise 'false'. Default value: 'false'

IS_DOTPRINT

is_dotprint

'true' if the text to be segmented is a dotprint, otherwise 'false'. Default value: 'false'

IS_IMPRINTED

is_imprinted

'true' if the text to be segmented suffers of local changes of polarity due to reflections, otherwise 'false'. Default value: 'false'

ELIMINATE_HORIZONTAL_LINES

eliminate_horizontal_lines

'true' if there are longer horizontal structures close to the text to be segmented, otherwise 'false'. Default value: 'false'

ELIMINATE_BORDER_BLOBS

eliminate_border_blobs

'true' if regions that are touching the border of the image domain should be discarded, otherwise 'false'. Default value: 'false'

MAX_LINE_NUM

max_line_num

Maximum number of lines to be found. Zero or negative values indicate no limitation. Setting 'max_line_num' to a low value may strongly improve the runtime of findText. Default value: no limitation

RETURN_PUNCTUATION

return_punctuation

'true' if punctuation marks (e.g., dots or comma) should be added to the segmented characters. Default value: 'true'

RETURN_SEPARATORS

return_separators

'true' if separators such as a minus or the equality sign should be added to the segmented characters. Default value: 'true'

ADD_FRAGMENTS

add_fragments

'true' if fragments, such as the dot on the 'i', should be added to the segmented characters. Be aware, that this can cause noise to be added to the segmented characters. Default value: 'true'

FRAGMENT_SIZE_MIN

fragment_size_min

minimum area of fragment regions that are added if 'add_fragments' is set to 'true'. List of values: integer value greater than or equal to 0. Default value: 1

TEXT_LINE_STRUCTURE

text_line_structure

To simplify the search for specific structures (e.g. dates or serial numbers) within the segmented text, it is possible to define text line structures. For each text line the distances between the characters are calculated, and based on these distances, the text line is divided into text blocks. Short characters such as '.', '_' and '-' are ignored in this process and treated as spaces. The text line structure is a string that contains the number of characters for every character block and spaces between these character blocks. For example, if the text to be found is a date with two characters for month, day, and year the structure would be '2 2 2'. If the year may consist of two or four characters, the structure would be '2 2 2-4', indicating that the last character block consists of two to four characters. It is possible to provide up to five structures to match by appending an index to the parameter name, e.g. 'text_line_structure_0', 'text_line_structure_1', etc. If 'text_line_structure' is set to an empty string '', the text to be found may have any structure. Please observe, that every text line structure which is found, is saved as in the text result even if they overlap. Default value: ''

Image.OutputGrid

Items
Value Name Description
SAME

SAME

The output is painted on the same pixel grid as the input.

FULL

FULL

The origin and size of the output image is adjusted to fit the entire output. The world pixel size of the input image is used.

Image.PixelRegion.Filter.FeatureType

Items
Value Name Description
CENTROIDX

centroid x

Center of gravity in world coordinates, x part. See getCenterOfGravity.

CENTROIDY

centroid y

Center of gravity in world coordinates, y part. See getCenterOfGravity.

PIXELCOUNT

pixel count

Number of region pixels. See countPixels

AREA

area

Region area in world units. See getArea.

VOLUME

volume

Volume in world units. See getVolume.

PERIMETER

perimiter

Region perimeter in world units. See getPerimeterLength.

LARGESTSIDE

largest side

Largest side of a minimum area rectangle in world units (min-area rectangle fitted with accuracy 0.1 degrees). See getBoundingBoxOriented.

SMALLESTSIDE

smallest side

Smallest side of a minimum area rectangle in world units (min-area rectangle fitted with accuracy 0.1 degrees). See getBoundingBoxOriented.

MAJORAXIS

major axis

Length of major principal axis in world units. See getPrincipalAxes.

MINORAXIS

minor axis

Length of minor principal axis in world units. See getPrincipalAxes.

ROTATION

rotation

Rotation of major principal axis in world units. See getPrincipalAxes.

ELONGATION

elongation

Ratio of major / minor axis lengths. See getElongation.

CONVEXITY

convexity

Ratio of area / convex hull area. See getConvexity.

COMPACTNESS

compactness

Compactness measure (4*PI*AREA) / PERIMETER^2. See getCompactness.

HOLESCOUNT

holes count

Number of holes. See countHoles.

TOUCHESBORDER

touches border

Touches border status (1 if region touches image border, 0 otherwise). See touchesImageBorder.

AVERAGEVALUE

average value

Average image intensity or height map value within the region. See getStatistics.

MINVALUE

min value

Minimum image intensity or height map value within the region. See getStatistics.

MAXVALUE

max value

Maximum image intensity or height map value within the region. See getStatistics.

STDDEVVALUE

std value

Standard deviation of image intensity or height map value within the region. See getStatistics.

MEDIANVALUE

median value

Median of image intensity or height map value within the region. See getMedian.

PERC10VALUE

percentile 10 value

10%-level (rank measure) of image intensity or height map value within the region (10% of all values are lower than this value). See getPercentiles.

PERC90VALUE

percentile 90 value

90%-level (rank measure) of image intensity or height map value within the region (90% of all values are lower than this value). See getPercentiles.

Image.ProcessingDimension

Items
Value Name Description
ROW

ROW

Do processing row-wise

COLUMN

COLUMN

Do processing column-wise

Image.Provider.Camera.V3TConfig2D.ImageTriggerMode

Items
Value Name Description
NONE

None (Continous)

Image acquisition is running continously

SOFTWARE

Software

Image acquistion is triggered by software call

Image.Provider.Camera.V3TConfig3D.ImageTriggerDelayUnit

Items
Value Name Description
MS

ms (milliseconds)

Delay is specified in milliseconds

MM

mm (millimeters)

Delay is specified in millimeters

Image.Provider.Camera.V3TConfig3D.ImageTriggerMode

Items
Value Name Description
NONE

None (Continous)

Image acquisition is running continously

OBJECT

Object

Image acquisition is triggered by objects higher than the threshold determined by setObjectTriggerLine

IO_3

I/O 3

Image acquisition is triggered by I/O 3 signal

SOFTWARE

Software

Image acquistion is triggered by Image.Provider.Camera.trigger()

Image.Provider.Camera.V3TConfig3D.PeakSelectionMode

Items
Value Name Description
STRONGEST

Strongest

Use the point with the strongest intensity in each column as the laser peak

TOP_MOST

Top most

Use the top most point with intensity greater than the configured laser threshold in each column as the laser peak

BOTTOM_MOST

Bottom most

Use the bottom most point with intensity greater than the configured laser threshold when detecting the laser peak

Image.Provider.Camera.V3TConfig3D.ProfileTriggerMode

Items
Value Name Description
FREE_RUNNING

Free running

Acquire images at a constant speed, not using an encoder

ENCODER

Encoder

Use a connected encoder to be able to handle variations in speed during image acquisition

Image.Pyramid.DownsamplingMethod

Items
Value Name Description
NEAREST

nearest

Downsample using nearest neighbor.

LINEAR

linear

Downsample using 2x2 linear interpolation.

GAUSSIAN

gaussian

Downsample using a Gaussian interpolation.

Image.Pyramid.ProcessingUnit

Items
Value Name Description
CPU

CPU

Calculations will be done on the CPU.

FPGA

FPGA

The FPGA will be used for hardware acceleration.

Image.ShapeFitter.EdgeSelection

Items
Value Name Description
STRONGEST

strongest

Strongest edge found

FIRST

first

First edge found

LAST

last

Last edge found

IncrementPortConnectors

Items
Value Name Description
INC1

INC1

LEDs

Items
Value Name Description
STATE_LED

LED State

Supported Colors: green

RESULT_LED

LED Result

Supported Colors: red, green, blue

LUA.math.Constants

Items
Value Name Description
math.huge

huge

The value HUGE_VAL, a value larger than or equal to any other numerical value.

math.pi

pi

The value of Pi (3.1415…​.).

LUA.utf8.Constants

Items
Value Name Description
utf8.charpattern

UTF8 Pattern

The pattern (a string, not a function) '[\0-\x7F\xC2-\xF4][\x80-\xBF]*' (see 6.4.1), which matches exactly one UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string.

Log.Level

Items
Value Name Description
OFF

Log nothing

SEVERE

Log only severe errors

WARNING

Log warnings and severe errors

INFO

Log infos, warnings and severe errors

FINE

Log fine, infos, warnings and severe errors

FINER

Log finer, fine, infos, warnings and severe errors

FINEST

Log finest, finer, fine, infos, warnings and severe errors

ALL

Log all messages

MachineLearning.DataSet.LabelType

Items
Value Name Description
CLASSIFICATION

CLASSIFICATION

Specify the use of discrete labels, this is what should be used when trying to separate distinct classes.

REGRESSION

REGRESSION

Specify the use of floating point labels. This is useful when the labels can be sorted or meaningfully compared.

MachineLearning.KMeansClustering.InitMethod

Items
Value Name Description
RANDOM

RANDOM

Place start centers for clusters at random

ESTIMATE

ESTIMATE

Try to estimate a good starting position

MachineLearning.NeuralNet.ActivationFunction

Items
Value Name Description
IDENTITY

IDENTITY

Identity activation function, eg. f(x) = x.

SIGMOID

SIGMOID

Sigmoid activation function, eg. f(x) ~ tanh(x).

GAUSSIAN

GAUSSIAN

Gaussian activation function, eg. f(x) ~ exp(-x^2).

MachineLearning.SupportVectorMachine.KernelType

Items
Value Name Description
LINEAR

LINEAR

Linear kernel. No mapping is done, linear discrimination (or regression) is done in the original feature space. It is the fastest option. K(x, y) = x^T * y.

GAUSSIAN

GAUSSIAN

Radial basis function (RBF), a good choice in most cases. K(x, y) = e^{-

x -

Monitor.App.AppStatus

The different possible status of an app.

Items
Value Name Description
UNKNOWN

UNKNOWN

RUNNING

RUNNING

STOPPED

STOPPED

CRASHED

CRASHED

MountedDrives

Items
Value Name Description
/ram

RAM

/sdcard/0

SDCARD

NTPClient.TimeSource

Items
Value Name Description
MANUAL

Manual

Don’t update the time over NTP

NTP

NTP

Update the time over NTP

OPCUA.AccessLevel

Possibilities to access a VARIABLE node value

Items
Value Name Description
READ

Read

The value is read only

READ_WRITE

ReadWrite

The value can be read and written

OPCUA.DataType

Enumeration of the supported OPC UA built-in data types

Items
Value Name Description
BYTE_STRING

ByteString

An array of unsigned bytes

BOOL

Bool

A boolean value

BYTE

Byte

An unsigned byte

SBYTE

SByte

A signed byte

INT16

Int16

A 16 bit signed integer

UINT16

UInt16

A 16 bit unsigned integer

INT32

Int32

A 32 bit signed integer

UINT32

UInt32

A 32 bit unsigned integer

INT64

Int64

A 64 bit signed integer

UINT64

UInt64

A 64 bit unsigned integer

FLOAT

Float

A 32 bit IEEE-754 floating point number

DOUBLE

Double

A 64 bit IEEE-754 floating point number

STRING

String

An UTF-8 String

STATUS_CODE

StatusCode

OPC UA StatusCode (see OPC UA specification part 4 (7.34))

DATE_TIME

DateTime

An instance in time (e.g., 1988-04-30T03:04:05Z; see OPC UA specification part 6 (5.2.2.5))

GUID

Guid

A globally unique identifier encoded as string (e.g., {72962B91-FA75-4AE6-8D28-B404DC7DAF63}, see OPC UA specification part 6 (5.2.2.6))

NODE_ID

NodeId

A node identifier encoded as string (e.g., "i=13" or "ns=12;s=Hello:World"; see OPC UA specification part 6 (5.3.1.10))

EXPANDED_NODE_ID

ExpandedNodeId

An expanded node identifier encoded as string (e.g., "svr=1;ns=2;s=Hello:World" or "svr=1;nsu=http://example.uri.com;s=Hello:World"; see OPC UA specification part 6 (5.3.1.11))

QUALIFIED_NAME

QualifiedName

A qualified name encoded as string of the form ">namespaceindex<:>name<" where namespace index is an unsigned 16 bit integer and name is a string (e.g., "1:some name"; see OPC UA specification part 3 (8.3))

LOCALIZED_TEXT

LocalizedText

A localized text as string of the form ">locale id<:>text<" where locale id is a locale string according to https://www.io.org/standard/57469.html and the actual localized text (e.g., "en-US:Hello World!" or "de:Hallo Welt!"; see OPC UA specification part 3 (8.4 and 8.5))

OPCUA.EventSeverity

Is mapped to OPC UA event severity (0 …​ 1000)

Items
Value Name Description
HIGHEST

Highest

Highest severity (1000)

HIGHER

Higher

Higher severity (900)

HIGH

High

High severity (800)

HIGHER_MEDIUM

HigherMedium

Higher than medium severity (650)

MEDIUM

Medium

Medium severity (500)

LOWER_MEDIUM

LowerMedium

Lower than medium severity (350)

LOW

Low

Low severity (200)

LOWER

Lower

Lower severity (100)

LOWEST

Lowest

Lowest severity (0)

OPCUA.NodeClass

All possible OPC UA node classes

Items
Value Name Description
OBJECT

Object

Node representing an object

VARIABLE

Variable

Node representing a (data) variable

METHOD

Method

Node representing a method

OBJECT_TYPE

ObjectType

Node representing an object type

VARIABLE_TYPE

VariableType

Node representing a variable type

REFERENCE_TYPE

ReferenceType

Node representing a reference type

DATA_TYPE

DataType

Node representing a data type

VIEW

View

Node representing a view

OPCUA.NodeIDType

Possible types of OPC UA node ID

Items
Value Name Description
NUMERIC

Numeric

An unsigned number is used; value range: 0-4294967295

STRING

String

A string should be used

OPCUA.NodeType

All supported OPC UA standard node types

Items
Value Name Description
BASE_DATA_VARIABLE_TYPE

BaseDataVariableType

The variable contains a potentially changeable value that represents data

PROPERTY_TYPE

PropertyType

The variable contains unchangeable data that expresses a property of another node

FOLDER_TYPE

FolderType

The object represents a folder

OPCUA.ReferenceType

Possible types of references from one OPC UA node to another

Items
Value Name Description
HAS_COMPONENT

HasComponent

The child node is a part of the parent node

HAS_ORDERED_COMPONENT

HasOrderedComponent

The child node is a part of the parent node; the child nodes are always returned in the same order on discovery

HAS_PROPERTY

HasProperty

The child node describes a property of the parent node, e.g. Input or Output arguments of a method

HAS_SUBTYPE

HasSubtype

The child node is a subtype of the parent node

HAS_EVENT_SOURCE

HasEventSource

The child node causes the parent node to generate an event

HAS_NOTIFIER

HasNotifier

The child node causes the parent node to generate an event, but generates also events itself

ORGANIZES

Organizes

The parent node is a folder which contains the child node

GENERATES_EVENT

GeneratesEvent

The child node describes which event is generated by the parent node (ObjectType, VariableType, Method)

ALWAYS_GENERATES_EVENT

AlwaysGeneratesEvent

The parent node (method) generates this event on each call

HAS_TYPE_DEFINITION

HasTypeDefinition

The definition of the type of the parent node (variable or object)

OPCUA.Server.SecurityConfiguration.MessageSecurityMode

This enum defines all possible message security modes to secure the message exchange between server and client. (cf. OPC UA specification, part 4, 7.15)

Items
Value Name Description
NONE

None

Do not sign or encrypt the messages.

SIGN

Sign

Sign the messages.

SIGN_AND_ENCRYPT

SignAndEncrypt

Sign and encrypt the messages.

OPCUA.Server.SecurityConfiguration.SecurityPolicy

This enum defines all security policies that can be used by a client to connect to the server.

Items
Value Name Description
NONE

None

Use the http://opcfoundation.org/UA/SecurityPolicy#None security policy, i.e. do not use any security.

BASIC_128_RSA_15

Basic128Rsa15

Use the http://opcfoundation.org/UA/SecurityPolicy#Basic128Rsa15 security policy.

BASIC_256

Basic256

Use the http://opcfoundation.org/UA/SecurityPolicy#Basic256 security policy.

BASIC_256_SHA_256

Basic256Sha256

Use the http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256 security policy.

OPCUA.Server.SecurityConfiguration.UserTokenPolicy

Defines all possible user token policies / authentication modes that the client can use to establish a connection to the server. (cf. OPC UA specification, part 4, 7.36.1)

Items
Value Name Description
ANONYMOUS

Anonymous

Use anonymous authentication.

USERNAME

Username

Use user name and password for authentication.

OPCUA.Server.Value.OptionalFieldState

Items
Value Name Description
DISABLED

DISABLED

The field is not present

ENABLED

ENABLED

The field ism present

OPCUA.Server.Value.UnionField

Items
Value Name Description
NO_FIELD

NO_FIELD

NO_FIELD

FIELD_1

FIELD_1

FIELD_1

FIELD_2

FIELD_2

FIELD_2

FIELD_3

FIELD_3

FIELD_3

FIELD_4

FIELD_4

FIELD_4

FIELD_5

FIELD_5

FIELD_5

FIELD_6

FIELD_6

FIELD_6

FIELD_7

FIELD_7

FIELD_7

FIELD_8

FIELD_8

FIELD_8

FIELD_9

FIELD_9

FIELD_9

FIELD_10

FIELD_10

FIELD_10

FIELD_11

FIELD_11

FIELD_11

FIELD_12

FIELD_12

FIELD_12

FIELD_13

FIELD_13

FIELD_13

FIELD_14

FIELD_14

FIELD_14

FIELD_15

FIELD_15

FIELD_15

FIELD_16

FIELD_16

FIELD_16

FIELD_17

FIELD_17

FIELD_17

FIELD_18

FIELD_18

FIELD_18

FIELD_19

FIELD_19

FIELD_19

FIELD_20

FIELD_20

FIELD_20

FIELD_21

FIELD_21

FIELD_21

FIELD_22

FIELD_22

FIELD_22

FIELD_23

FIELD_23

FIELD_23

FIELD_24

FIELD_24

FIELD_24

FIELD_25

FIELD_25

FIELD_25

FIELD_26

FIELD_26

FIELD_26

FIELD_27

FIELD_27

FIELD_27

FIELD_28

FIELD_28

FIELD_28

FIELD_29

FIELD_29

FIELD_29

FIELD_30

FIELD_30

FIELD_30

FIELD_31

FIELD_31

FIELD_31

FIELD_32

FIELD_32

FIELD_32

Object.DataFormat

In what kind of format data should be read/written

Items
Value Name Description
JSON

JSON

MSGPACK

MessagePack

Point.NormType

Items
Value Name Description
L_1_NORM

L-1-Norm

Manhattan distance:

x

+

y

+

z

L_2_NORM

L-2-Norm

Euclidean distance: sqrt(x*x+y*y+z*z)

L_INFINITY_NORM

L-Infinity-Norm

Maximum of absolute values: max(

x

,

y

,

z

)

PointCloud.ColorMode

Items
Value Name Description
INTENSITY

Intensity

Intensity values from 0.0 to 1.0

RGBA

RGBA

Red, Green, Blue, Alpha values from 0 to 255

PointCloud.Matching.Halcon.SurfaceMatcher.NormalComputationMethod

Items
Value Name Description
MLS

MLS

Moving least-squares method for more accurate normal estimation.

FAST

Fast

Fast approximate normal estimation method using a small neighborhood.

PointCloud.toImageMode

Items
Value Name Description
TOPMOST

topmost

Resolve point ambiguities by picking the upper point, i.e, prioritize points with higher z coordinate.

BOTTOMMOST

bottommost

Resolve point ambiguities by picking the lower point,i.e, prioritize points with a lower z coordinate.

Profile.AggregateOperation

Items
Value Name Description
SUM

sum

Sum of values.

MIN

min

Minimal value.

MAX

max

Maximal value.

MEAN

mean

Mean value.

MEDIAN

median

Median value.

Profile.ContrastDifferenceMode

Items
Value Name Description
ONE

one

At least one point on each side in the neighborhood should have the specified value margin to the extremal point.

ALL

all

All points in the neighborhood should have the specified value margin to the extremal point.

Profile.CoordinateType

Items
Value Name Description
IMPLICIT_1D

implicit_1d

Squared difference.

EXPLICIT_1D

explicit_1d

Squared difference.

IMPLICIT_2D

implicit_2d

Squared difference.

EXPLICIT_2D

explicit_2d

Squared difference.

Profile.Curve.CurveType

Items
Value Name Description
POLYNOMIAL

Polynomial

Polynomial function.

EXPONENTIAL

Exponential

Exponential function.

GAUSSIAN

Gaussian

Gaussian function.

Profile.CurveFitter.CurveFitMode

Items
Value Name Description
LEAST_SQUARES

least_squares

Ordinary least squares.

RANSAC

ransac

Ransac (random sampling with outlier rejection).

Profile.CurveFitter.CurveOutlierMarginType

Items
Value Name Description
RANK

rank

Rank-based margin, defines the rate of points to include. For example, A rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored.

ABSOLUTE

absolute

Absolute outlier margin.

Profile.DifferenceMode

Items
Value Name Description
ABS

abs

Absolute difference.

SQUARE

square

Squared difference.

Profile.DifferentiationOrder

Items
Value Name Description
FIRST

first

First order

SECOND

second

Second order

Profile.EdgeSide

Items
Value Name Description
HIGH

high

Snap to the high side of the slope

LOW

low

Snap to the low side of the slope

CENTER

center

Snap to the slope center (point of maximal derivative)

Profile.ExtremaType

Items
Value Name Description
MAX

max

Local maxima

MIN

min

Local minima

Profile.FillInvalidMethod

Items
Value Name Description
LINEAR

linear

Squared difference.

NEIGHBOR_MIN

neighbor_min

Squared difference.

NEIGHBOR_MAX

neighbor_max

Squared difference.

NEIGHBOR_MEAN

neighbor_mean

Squared difference.

Profile.ImageType

Items
Value Name Description
INT8

int8

signed 8-bit integer

INT16

int16

signed 16-bit integer

INT32

int32

signed 32-bit integer

INT64

int64

signed 64-bit integer

UINT8

uint8

unsigned 8-bit integer

UINT16

uint16

unsigned 16-bit integer

UINT32

uint32

unsigned 32-bit integer

UINT64

uint64

unsigned 64-bit integer

FLOAT32

float32

32-bit floating-point

FLOAT64

float64

64-bit floating-point

Profile.Matching.PatternMatcher.ComparisonMode

Items
Value Name Description
XCORRNORM

xCorrNorm

Cross correlation with normalization.

SAD

sad

Sum of absolute difference.

Profile.NoiseType

Items
Value Name Description
NORMAL

normal

Normal distribution.

UNIFORM

uniform

Uniform distribution.

Profile.SlopePolarity

Items
Value Name Description
POSITIVE

positive

Positive slope (low to high value)

NEGATIVE

negative

Negative slope (high to low value)

ANY

any

Either positive or negative

Profile.SortKey

Items
Value Name Description
BY_VALUE

by_value

Sort by value.

BY_COORDINATE

by_coordinate

Sort by coordinate.

Script.Priority

Items
Value Name Description
LOW

Low priority

MEDIUM

Medium priority

HIGH

High priority

Script.Queue.Priority

The relative priority for scripts compared to other queues

Items
Value Name Description
HIGH

High

MID

Middle (Default)

LOW

Low

SerialComTypes

Items
Value Name Description
RS232

Default

SerialPorts

Items
Value Name Description
SER1

SER1

This serial interface supports SerialType RS232

Shape.OutlierMarginType

Items
Value Name Description
ABSOLUTE

absolute

Absolute outlier margin, defined in world coordinate units (typically mm).

RANK

rank

Rank-based margin, defines the rate of points to include. For example, A rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored.

Shape.PointFitMode

Items
Value Name Description
LEASTSQUARES

leastsquares

Ordinary least squares

RANSAC

ransac

Ransac (random sampling with outlier rejection)

ADAPTIVE

adaptive

Ransac with rank-margin. This mode is deprecated and may be removed in a future version. Please use RANSAC and call setOutlierMargin with the margin type set to RANK instead.

TRIMMED

trimmed

Two-stage least squares fitting. The second stage uses only points within the margin around the fitted shape of the first stage.

Shape.ShapeType

Items
Value Name Description
LINE

Line

Line shape (infinite length)

LINE_SEGMENT

Line segment

Line segment shape

POLYLINE

Polyline

Polyline shape, open or closed

RECTANGLE

Rectangle

Rectangle shape (possibly rotated)

CIRCLE

Circle

Circle shape

ELLIPSE

Ellipse

Ellipse shape

ARC

Arc

Arc shape, i.e. a part of a circle contour limited by two angles

SECTOR

Sector

Sector shape enclosing a region limited by two angles, an inner and an outer radius

Shape3D.Shape3DType

Items
Value Name Description
PLANE

Plane

Plane (with infinite size)

LINE

Line

Line in 3D (infinite length)

LINE_SEGMENT

Line segment

Line segment in 3D

RECTANGLE

Rectangle

2D rectangle in 3D space

CIRCLE

Circle

2D circle in 3D space

ELLIPSE

Ellipse

2D ellipse in 3D space

POLYGON

Polygon

A closed planar 2D polygon in 3D space

BOX

Box

Solid 3D box

CYLINDER

Cylinder

Solid cylinder

ELLIPTIC_CYLINDER

EllipticCylinder

Solid elliptic cylinder (elliptic base area extended with a height)

CONE

Cone

A 3D cone

SPHERE

Sphere

Sphere

POLYLINE

Polyline

An open polyline in 3D

Shape3D.ShapePointFitMode

Items
Value Name Description
LEASTSQUARES

leastsquares

Ordinary least squares

RANSAC

ransac

Ransac (random sampling with outlier rejection)

TRIMMED

trimmed

Two-stage least squares fitting. The second stage uses only points within the margin around the fitted shape of the first stage.

Statistics.HistogramCompareMethod

Items
Value Name Description
L1

L1 norm

Sum of absolute differences

L2

L2 norm

Euclidean norm, square root of sum of square differences

MAXDIFF

Maximal difference

Maximal difference between corresponding bins (L-infinity norm)

CHI2

Chi-square statistic

Chi-square statistic (normalized sum of squares). This is the default method and should work well in most cases.

KLDIV

Kullback-Leibler divergence

Kullback-Leibler divergence: sum(p[i] * log(p[i] / q[i])

Transform.RotationOrder

Items
Value Name Description
XYZ

XYZ

Rotation first around the world x-axis, then the world y-axis and last the world z-axis.

ZYX

ZYX

Rotation first around the world z-axis, then the world y-axis and last the world x-axis.

ZYZ

ZYZ

Rotation first around the world z-axis, then the world y-axis and last the world z-axis.

Transform.TransformType

Items
Value Name Description
IDENTITY

Identity

Identity transform

TRANSLATION

Translation

A translation transform shifts an object along the x, y and z axes

RIGID

Rigid

A rigid transform rotates and translates an object

SIMILARITY

Similarity

A similarity transform scales, rotates and translates an object

AFFINE

Affine

An affine transform shears, scales, rotates and translates and object

HOMOGRAPHY

Homography

A homography transform, also known as a projective transform, is the most general linear transform. It includes affine, similarity and rigid transforms as special cases.

TriSpector.DeviceVariant

Items
Value Name Description
TriSpectorP 1008

TriSpectorP 1008

TriSpectorP 1008 device variant

TriSpectorP 1030

TriSpectorP 1030

TriSpectorP 1030 device variant

TriSpectorP 1060

TriSpectorP 1060

TriSpectorP 1060 device variant

View.Channel

Items
Value Name Description
LIVE

LIVE

In case of queues on the channel, only the latest presented iconics will be delivered. This is the default value for View.present().

ASSURED

ASSURED

None of the presented iconics will be discarded.

View.ColorMap.ColorMapType

Items
Value Name Description
LINEAR

LINEAR

Smooth linear transition between color stops

DISCRETE

DISCRETE

Discrete color jumps at the color stops

View.ColorMap.PredefinedColorMap

Items
Value Name Description
AUTUMN

AUTUMN

red → yellow

BLUE_WHITE_RED

BLUE_WHITE_RED

blue → white → red

COOL

COOL

aqua → fuchsia

GRAY

GRAY

black → white

HOT

HOT

black → red → yellow → white

HSV

HSV

red → yellow → green → aqua → blue → fuchsia → red

JET

JET

blue → aqua → green → yellow → red

RAINBOW

RAINBOW

red → fuchsia → blue → aqua → green → yellow → red

SPRING

SPRING

fuchsia → yellow

SUMMER

SUMMER

deep sea → lemon

THERMAL

THERMAL

black → pink → orange → yellow → white

TRAFFIC_LIGHT

TRAFFIC_LIGHT

red → yellow → green

WINTER

WINTER

blue → spring green

RGB

RGB

red → green → blue

View.GraphDecoration.AspectRatio

Items
Value Name Description
EQUAL

EQUAL

Equal aspect ratio (both axis has the same scaling)

SQUARE

SQUARE

Square aspect ratio

FIT

FIT

Fitting the viewer

View.GraphDecoration.GraphType

Items
Value Name Description
DOT

DOT

Dot graph

LINE

LINE

Line graph

BAR

BAR

Bar graph

View.MeshDecoration.VisibleFaces

Items
Value Name Description
FRONT

FRONT

Renders the front faces. A front face exists if the triangle vertices, in order, rotate clockwise around the triangle’s center.

BACK

BACK

Renders the back faces. A back face exists if the triangle vertices, in order, rotate counter-clockwise around the triangle’s center.

FRONT_AND_BACK

FRONT_AND_BACK

Renders both front and back faces.

NONE

NONE

Does not render the triangle faces. It can be used for example if only the vertex points are rendered.

View.PointerActionType

Items
Value Name Description
CLICKED

CLICKED

DOWN

DOWN

UP

UP

View.PointerType

Items
Value Name Description
PRIMARY

PRIMARY

SECONDARY

SECONDARY

MIDDLE

MIDDLE

View.Present.Add.IconicType

Items
Value Name Description
HEIGHTMAP

HEIGHTMAP

Add heightmap type

IMAGE

IMAGE

Add image type

PIXEL_REGION

PIXEL_REGION

Add pixel region type

POINT_CLOUD

POINT_CLOUD

Add point cloud type

SHAPE

SHAPE

Add shape type

TEXT

TEXT

Add text type

PROFILE

PROFILE

Add profile type

POLAR_SCAN

POLAR_SCAN

Add polar scan type

MESH

MESH

Add mesh type

View.Present.Editor.EditorType

Items
Value Name Description
INSTALL

INSTALL

Install editor

UNINSTALL

UNINSTALL

Uninstall editor

View.Present.LogLevel

Items
Value Name Description
INFO

INFO

Log level for info

WARNING

WARNING

Log level for warnings

ERROR

ERROR

Log level for errors

View.ShapeDecoration.PointType

Items
Value Name Description
DOT

DOT

a dot to present the point

CROSS

CROSS

a cross to present the point

View.TextDecoration.FontFamily

Items
Value Name Description
SANSSERIF

SANSSERIF

Sans Serif font, e.g., Arial, Helvetica style.

MONOSPACE

MONOSPACE

Mono-spaced font, e.g., Courier style.

SERIF

SERIF

Serif font, e.g., Times New Roman style.

View.TextDecoration.HorizontalAlignment

Items
Value Name Description
LEFT

LEFT

Align text to the left of the given position.

CENTER

CENTER

Align text centered horizontally relative to given position.

RIGHT

RIGHT

Align text to the right of the given position.

JUSTIFY

JUSTIFY

Align text in a justified mode (stretch spaces to fill the bound’s width).

View.TextDecoration.VerticalAlignment

Items
Value Name Description
BOTTOM

BOTTOM

Align bottom of text with the given position.

CENTER

CENTER

Align center of text with the given position.

TOP

TOP

Align top of text with the given position.

Data formats

C

Container

D

DateTime

E

EncoderData

I

Image Image.Calibration.CameraModel Image.Fixture Image.Fixture3D Image.Matching.EdgeMatcher Image.Matching.EdgeMatcher3D Image.Matching.PointMatcher Image.PixelRegion

M

MachineLearning.DataSet Matrix Mesh

P

Parameters.Node Parameters.Node.Array Parameters.Node.Struct Parameters.Node.Variant Point Point2D Point3D Point3D_32 PointCloud PointCloud.XYZI Profile Profile.Curve Profile.Curve.Exponential Profile.Curve.Gaussian Profile.Curve.Polynomial Profile.Log

S

SensorData Shape Shape.Arc Shape.Circle Shape.Composite Shape.Ellipse Shape.Line Shape.LineSegment Shape.PolyLine Shape.Rectangle Shape.Sector Shape3D Shape3D.Box Shape3D.Circle Shape3D.Cone Shape3D.Cylinder Shape3D.Ellipse Shape3D.EllipticCylinder Shape3D.Line Shape3D.LineSegment Shape3D.Plane Shape3D.Polygon Shape3D.Polyline Shape3D.Rectangle Shape3D.Sphere

T

Transform Transform2D Transform3D

V

View.Camera View.ColorMap View.GraphDecoration View.GraphDecoration.ASPECTRATIO View.GraphDecoration.GRAPHTYPE View.GraphDecoration.RGBA View.ImageDecoration View.ImageDecoration.DataRange View.MeshDecoration View.MeshDecoration.VisibleFaces View.PixelRegionDecoration View.PixelRegionDecoration.RGBA View.PointCloudDecoration View.Present.Add View.Present.Clear View.Present.Editor View.Present.Remove View.Present.UpdateDecoration View.Present.UpdateTransform View.ShapeDecoration View.ShapeDecoration.Pixel.RGBA View.ShapeDecoration.PointType View.TextDecoration View.TextDecoration.Bounds View.TextDecoration.FontFamily View.TextDecoration.FontWeight View.TextDecoration.HorizontalAlignment View.TextDecoration.RGBA View.TextDecoration.VerticalAlignment

Container

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Content">
            <array>
                <item>
                    <struct>
                        <item name="Key">
                            <string/>
                        </item>
                        <item name="Type">
                            <string/>
                        </item>
                        <item name="IsVector">
                            <bool/>
                        </item>
                        <item name="Value">
                            <any_of>
                                <item>
                                    <int signed="true" width="64"/>
                                </item>
                                <item>
                                    <int signed="false" width="64"/>
                                </item>
                                <item>
                                    <float width="64"/>
                                </item>
                                <item>
                                    <bool/>
                                </item>
                                <item>
                                    <string/>
                                </item>
                                <item>
                                    <polymorphic/>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <int signed="true" width="64"/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <int signed="false" width="64"/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <float width="64"/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <bool/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <string/>
                                        </item>
                                    </array>
                                </item>
                                <item>
                                    <array>
                                        <item>
                                            <polymorphic/>
                                        </item>
                                    </array>
                                </item>
                            </any_of>
                        </item>
                    </struct>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Container",
  "data" : {
    "Content" : [ {
      "Key" : "valKey1",
      "Type" : "int",
      "IsVector" : false,
      "Value" : 5
    }, {
      "Key" : "valKey2",
      "Type" : "string",
      "IsVector" : false,
      "Value" : "stringval"
    }, {
      "Key" : "valKey3",
      "Type" : "object",
      "IsVector" : false,
      "Value" : {
        "class" : "MyObject",
        "data" : {
          "somevalue" : "stringval"
        }
      }
    }, {
      "Key" : "valKey4",
      "Type" : "float",
      "IsVector" : true,
      "Value" : [ 1.0, 2.0, 3.0 ]
    } ]
  }
}

DateTime

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="ExtendedUnixTime" desc="Unix time plus fraction of a second">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "DateTime",
  "data" : {
    "ExtendedUnixTime" : 1.570779685528E9
  }
}

EncoderData

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Position" desc="Encoder position incremental value">
            <int signed="false" width="32"/>
        </item>
        <item name="Speed" desc="Speed in m/s">
            <float width="32"/>
        </item>
        <item name="SystemIncrement" desc="System increment value; application specific">
            <int signed="false" width="32"/>
        </item>
        <item name="TimestampUTC" desc="UTC time stamp in floating-point seconds">
            <float width="64"/>
        </item>
        <item name="TimestampUS" desc="Application specific, relative time stamp in microseconds">
            <int signed="false" width="64"/>
        </item>
        <item name="xValue" desc="Corresponding x-value if available. Application specific">
            <int signed="false" width="32"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "EncoderData",
  "data" : {
    "Position" : 0,
    "Speed" : 0,
    "SystemIncrement" : 0,
    "TimestampUTC" : 0,
    "TimestampUS" : 0,
    "xValue" : 0
  }
}

Image

Directly referenced data formats

Point3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="PixelSize" desc="Size of the image pixel in some coordinate system (application defined). Usage is optional.">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="Origin" desc="Application defined coordinate of the top left pixel. Usage is optional.">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="HandleZeroPixels" desc="How pixels with value zero are interpreted">
            <any_of>
                <item desc="Pixels with value 0 are real pixels">
                    <string value="Default"/>
                </item>
                <item desc="Pixels with value 0 indicate missing data and are no 'real' value">
                    <string value="MissingData"/>
                </item>
            </any_of>
        </item>
        <item name="Data">
            <struct>
                <item name="ImageType">
                    <any_of>
                        <item>
                            <string value="uint8"/>
                        </item>
                        <item>
                            <string value="uint16"/>
                        </item>
                        <item>
                            <string value="uint32"/>
                        </item>
                        <item>
                            <string value="uint64"/>
                        </item>
                        <item>
                            <string value="int8"/>
                        </item>
                        <item>
                            <string value="int16"/>
                        </item>
                        <item>
                            <string value="int32"/>
                        </item>
                        <item>
                            <string value="int64"/>
                        </item>
                        <item>
                            <string value="float32"/>
                        </item>
                        <item>
                            <string value="float64"/>
                        </item>
                        <item>
                            <string value="RGB24"/>
                        </item>
                    </any_of>
                </item>
                <item name="Width">
                    <int signed="true" width="32"/>
                </item>
                <item name="Height">
                    <int signed="true" width="32"/>
                </item>
                <item name="Pixels">
                    <any_of>
                        <item>
                            <big_data_array>
                                <element_type name="uint8" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="uint16" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="uint32" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="uint64" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="int8" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="int16" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="int32" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="int64" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="float32" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="float64" desc="The pixel content"/>
                            </big_data_array>
                        </item>
                        <item>
                            <big_data_array>
                                <element_type name="uint8" desc="The BLUE pixel content"/>
                                <element_type name="uint8" desc="The GREEN pixel content"/>
                                <element_type name="uint8" desc="The RED pixel content"/>
                            </big_data_array>
                        </item>
                    </any_of>
                </item>
            </struct>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Image",
  "data" : {
    "PixelSize" : {
      "x" : 1,
      "y" : 1,
      "z" : 1
    },
    "Origin" : {
      "x" : 0,
      "y" : 0,
      "z" : 0
    },
    "HandleZeroPixels" : "Default",
    "Data" : {
      "ImageType" : "RGB24",
      "Width" : 2,
      "Height" : 2,
      "Pixels" : {
        "numOfElems" : 4,
        "elemSz" : 3,
        "endian" : "neutral",
        "elemTypes" : [ "uint8", "uint8", "uint8" ],
        "data" : "AgEABQQDCAcGCwoJ"
      }
    }
  }
}

Image.Calibration.CameraModel

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="CameraID" desc="Unique camera identifier">
            <string/>
        </item>
        <item name="ImageWidth" desc="Image width for which the calibration is valid">
            <int signed="true" width="32"/>
        </item>
        <item name="ImageHeight" desc="Image height for which the calibration is valid">
            <int signed="true" width="32"/>
        </item>
        <item name="FocalDistance" desc="Distance from the camera to the plane of best image sharpness">
            <float width="64"/>
        </item>
        <item name="FocalDistanceUnit" desc="Focus distance unit (Default is mm)">
            <string/>
        </item>
        <item name="IntrinsicK">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
        <item name="WorldToSensorDistortion">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
        <item name="SensorToWorldDistortion">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
        <item name="WorldToView">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Image.Calibration.CameraModel",
  "data" : {
    "CameraID" : "",
    "ImageWidth" : 0,
    "ImageHeight" : 0,
    "FocalDistance" : 0,
    "FocalDistanceUnit" : "",
    "IntrinsicK" : [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ],
    "WorldToSensorDistortion" : [ [ 0 ], [ 0 ], [ 0 ], [ 0 ], [ 0 ] ],
    "SensorToWorldDistortion" : [ [ 0 ], [ 0 ], [ 0 ], [ 0 ], [ 0 ] ],
    "WorldToView" : [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]
  }
}

Image.Fixture

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="PointsNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Points">
            <array>
                <item>
                    <struct>
                        <item name="x">
                            <float width="64"/>
                        </item>
                        <item name="y">
                            <float width="64"/>
                        </item>
                    </struct>
                </item>
            </array>
        </item>
        <item name="ShapesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Shapes">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="CompositeShapesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="CompositeShapes">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="AnglesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Angles">
            <array>
                <item>
                    <float width="64"/>
                </item>
            </array>
        </item>
        <item name="PosesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Poses">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="TeachPoseSet">
            <bool/>
        </item>
        <item name="TransformSet">
            <bool/>
        </item>
        <item name="TeachToMatch">
            <polymorphic/>
        </item>
        <item name="TeachToModel">
            <polymorphic/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Image.Fixture",
  "data" : {
    "PointsNames" : [ "thePoint_0", "thePoint_1" ],
    "Points" : [ {
      "x" : 50,
      "y" : 1000
    }, {
      "x" : 51,
      "y" : 1001
    } ],
    "ShapesNames" : [ "theShape_0", "theShape_1" ],
    "Shapes" : [ "Shape.Circle", "Shape.Line" ],
    "CompositeShapesNames" : [ "theCompositeShape_0", "theCompositeShape_1" ],
    "CompositeShapes" : [ "Shape.Composite", "Shape.Composite" ],
    "AnglesNames" : [ "theAngle_0", "theAngle_1" ],
    "Angles" : [ 1.1, 1.2 ],
    "PosesNames" : [ "thePose_0", "thePose_1" ],
    "Pose" : [ "Transform2D", "Transform2D" ],
    "TeachPoseSet" : "true",
    "TransformSet" : "true",
    "TeachToMatch" : "Transform2D",
    "TeachToModel" : "Transform2D"
  }
}

Image.Fixture3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="PointsNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Points">
            <array>
                <item>
                    <struct>
                        <item name="x">
                            <float width="64"/>
                        </item>
                        <item name="y">
                            <float width="64"/>
                        </item>
                        <item name="z">
                            <float width="64"/>
                        </item>
                    </struct>
                </item>
            </array>
        </item>
        <item name="ShapesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Shapes">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="PosesNames">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="Poses">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="TeachPoseSet">
            <bool/>
        </item>
        <item name="TransformSet">
            <bool/>
        </item>
        <item name="TeachToMatch">
            <polymorphic/>
        </item>
        <item name="TeachToModel">
            <polymorphic/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Image.Fixture3D",
  "data" : {
    "PointsNames" : [ "thePoint_0", "thePoint_1" ],
    "Points" : [ {
      "x" : 50,
      "y" : 1000
    }, {
      "x" : 51,
      "y" : 1001
    } ],
    "ShapesNames" : [ "theShape_0", "theShape_1" ],
    "Shapes" : [ "Shape.Circle", "Shape.Line" ],
    "PosesNames" : [ "thePose_0", "thePose_1" ],
    "Pose" : [ "Transform3D", "Transform3D" ],
    "TeachPoseSet" : "true",
    "TransformSet" : "true",
    "TeachToMatch" : "Transform3D",
    "TeachToModel" : "Transform3D"
  }
}

Image.Matching.EdgeMatcher

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Version">
            <int signed="true" width="32"/>
        </item>
        <item name="Params">
            <struct>
                <item name="EdgeThreshold">
                    <struct>
                        <item name="x">
                            <float width="64"/>
                        </item>
                        <item name="y">
                            <float width="64"/>
                        </item>
                    </struct>
                </item>
                <item name="ProcessingUnit">
                    <int signed="true" width="32"/>
                </item>
            </struct>
        </item>
        <item name="TimeoutSeconds">
            <float width="64"/>
        </item>
        <item name="Matcher">
            <string/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Image.Matching.EdgeMatcher",
  "data" : {
    "Params" : {
      "Version" : 2,
      "EdgeThreshold" : {
        "x" : 50,
        "y" : 1000
      },
      "ProcessingUnit" : 1
    },
    "TimeoutSeconds" : 5,
    "Matcher" : "aa"
  }
}

Image.Matching.EdgeMatcher3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Version">
            <int signed="true" width="32"/>
        </item>
        <item name="Params">
            <struct>
                <item name="EdgeThreshold">
                    <struct>
                        <item name="x">
                            <float width="64"/>
                        </item>
                        <item name="y">
                            <float width="64"/>
                        </item>
                    </struct>
                </item>
                <item name="ProcessingUnit">
                    <int signed="true" width="32"/>
                </item>
            </struct>
        </item>
        <item name="TimeoutSeconds">
            <float width="64"/>
        </item>
        <item name="ReferencePlaneSet">
            <bool/>
        </item>
        <item name="Matcher">
            <string/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Image.Matching.EdgeMatcher3D",
  "data" : {
    "Version" : 2,
    "Params" : {
      "EdgeThreshold" : {
        "x" : 50,
        "y" : 1000
      },
      "ProcessingUnit" : 1
    },
    "TimeoutSeconds" : 5,
    "ReferencePlaneSet" : true,
    "Matcher" : "aa"
  }
}

Image.Matching.PointMatcher

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Version">
            <int signed="true" width="32"/>
        </item>
        <item name="Matcher">
            <string/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Image.Matching.PointMatcher",
  "data" : {
    "Version" : 2,
    "Matcher" : "aa"
  }
}

Image.PixelRegion

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="segments" desc="Structs for individual segments of a run-length coded region">
            <big_data_array>
                <element_type name="int32" desc="y: Image row of the segment"/>
                <element_type name="int32" desc="xStart: x-coordinate of first included pixel"/>
                <element_type name="int32" desc="xStop: x-coordinate of last included pixel"/>
            </big_data_array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Image.PixelRegion",
  "data" : {
    "segments" : {
      "numOfElems" : 2,
      "elemSz" : 12,
      "endian" : "little",
      "elemTypes" : [ "int32", "int32", "int32" ],
      "data" : "AQAAAAIAAAADAAAABAAAAAUAAAAGAAAA"
    }
  }
}

MachineLearning.DataSet

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Revision">
            <int signed="true" width="32"/>
        </item>
        <item name="Width">
            <int signed="true" width="32"/>
        </item>
        <item name="Height">
            <int signed="true" width="32"/>
        </item>
        <item name="LabelType">
            <any_of>
                <item>
                    <string value="Classification"/>
                </item>
                <item>
                    <string value="Regression"/>
                </item>
            </any_of>
        </item>
        <item name="WeightsExist">
            <bool/>
        </item>
        <item name="Samples">
            <big_data_array>
                <element_type name="float32"/>
            </big_data_array>
        </item>
        <item name="Labels">
            <any_of>
                <item>
                    <big_data_array>
                        <element_type name="float32"/>
                    </big_data_array>
                </item>
                <item>
                    <big_data_array>
                        <element_type name="int32"/>
                    </big_data_array>
                </item>
            </any_of>
        </item>
        <item name="Weights">
            <big_data_array>
                <element_type name="float32"/>
            </big_data_array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "MachineLearning.DataSet",
  "data" : {
    "Revision" : 0,
    "Width" : 0,
    "Height" : 0,
    "LabelType" : "Classification",
    "WeightsExist" : false,
    "Samples" : {
      "numOfElems" : 0,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "float32" ],
      "data" : ""
    },
    "Labels" : {
      "numOfElems" : 0,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "int32" ],
      "data" : ""
    },
    "Weights" : {
      "numOfElems" : 0,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "float32" ],
      "data" : ""
    }
  }
}

Matrix

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Rows" desc="Matrix height (in number of elements)">
            <int signed="true" width="32"/>
        </item>
        <item name="Columns" desc="Matrix width (in number of elements)">
            <int signed="true" width="32"/>
        </item>
        <item name="Elements" desc="Matrix elements in row-major storage order">
            <big_data_array>
                <element_type name="float64" desc="Single matrix element"/>
            </big_data_array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Matrix",
  "data" : {
    "Rows" : 2,
    "Columns" : 2,
    "Elements" : {
      "numOfElems" : 4,
      "elemSz" : 8,
      "endian" : "little",
      "elemTypes" : [ "float64" ],
      "data" : "kiRJkiRJwj+SJEmSJEnSP9u2bdu2bds/kiRJkiRJ4j8="
    }
  }
}

Mesh

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Indices" desc="List of triangle indices">
            <big_data_array>
                <element_type name="uint32" desc="Vertex index"/>
            </big_data_array>
        </item>
        <item name="Vertices" desc="Vertex position coordinates">
            <big_data_array>
                <element_type name="float32" desc="X coordinate"/>
                <element_type name="float32" desc="Y coordinate"/>
                <element_type name="float32" desc="Z coordinate"/>
            </big_data_array>
        </item>
        <item name="Normals" desc="Vertex normal vectors">
            <big_data_array>
                <element_type name="float32" desc="X coordinate"/>
                <element_type name="float32" desc="Y coordinate"/>
                <element_type name="float32" desc="Z coordinate"/>
            </big_data_array>
        </item>
        <item name="Colors" desc="Vertex color vectors">
            <big_data_array>
                <element_type name="uint8" desc="Red"/>
                <element_type name="uint8" desc="Green"/>
                <element_type name="uint8" desc="Blue"/>
                <element_type name="uint8" desc="Alpha"/>
            </big_data_array>
        </item>
        <item name="Intensities" desc="Vertex intensities">
            <big_data_array>
                <element_type name="float32" desc="Intensity"/>
            </big_data_array>
        </item>
        <item name="TexCoords" desc="Vertex texture coordinates">
            <big_data_array>
                <element_type name="float32" desc="S coordinate"/>
                <element_type name="float32" desc="T coordinate"/>
            </big_data_array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Mesh",
  "data" : {
    "Indices" : {
      "numOfElems" : 6,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "uint32" ],
      "data" : "AAAAAAEAAAACAAAAAQAAAAIAAAADAAAA"
    },
    "Vertices" : {
      "numOfElems" : 4,
      "elemSz" : 12,
      "endian" : "little",
      "elemTypes" : [ "float32", "float32", "float32" ],
      "data" : "AAAAAAAAAAAAAAAAAAAAAAAAgD8AAAAAAACAPwAAAAAAAAAAAACAPwAAgD8AAAAA"
    },
    "Normals" : {
      "numOfElems" : 4,
      "elemSz" : 12,
      "endian" : "little",
      "elemTypes" : [ "float32", "float32", "float32" ],
      "data" : "AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/"
    },
    "Colors" : {
      "numOfElems" : 4,
      "elemSz" : 4,
      "endian" : "neutral",
      "elemTypes" : [ "uint8", "uint8", "uint8", "uint8" ],
      "data" : "/wAA////AP///wD/AP8A/w=="
    },
    "Intensities" : {
      "numOfElems" : 4,
      "elemSz" : 4,
      "endian" : "little",
      "elemTypes" : [ "float32" ],
      "data" : "zczMPc3MTD6amZk+zczMPg=="
    },
    "TexCoords" : {
      "numOfElems" : 4,
      "elemSz" : 8,
      "endian" : "little",
      "elemTypes" : [ "float32", "float32" ],
      "data" : "AAAAAAAAAAAAAAAAAACAPwAAgD8AAAAAAAAAAAAAgD8="
    }
  }
}

Parameters.Node

Directly referenced data formats

Parameters.Node.Variant

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="type">
            <any_of>
                <item>
                    <string value="SInt"/>
                </item>
                <item>
                    <string value="Int"/>
                </item>
                <item>
                    <string value="DInt"/>
                </item>
                <item>
                    <string value="LInt"/>
                </item>
                <item>
                    <string value="USInt"/>
                </item>
                <item>
                    <string value="UInt"/>
                </item>
                <item>
                    <string value="UDInt"/>
                </item>
                <item>
                    <string value="ULInt"/>
                </item>
                <item>
                    <string value="Real"/>
                </item>
                <item>
                    <string value="LReal"/>
                </item>
                <item>
                    <string value="Bool"/>
                </item>
                <item>
                    <string value="String"/>
                </item>
                <item>
                    <string value="Array"/>
                </item>
                <item>
                    <string value="Struct"/>
                </item>
            </any_of>
        </item>
        <item name="value">
            <data_format_ref name="Parameters.Node.Variant"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Parameters.Node",
  "data" : {
    "type" : "Int",
    "value" : 0
  }
}

Parameters.Node.Array

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="type">
            <string/>
        </item>
        <item name="value">
            <array>
                <item>
                    <data_format_ref name="Parameters.Node.Variant"/>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "type" : "Int",
  "value" : [ 1, 1, 3 ]
}

Parameters.Node.Struct

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <array>
        <item>
            <struct>
                <item name="name">
                    <string/>
                </item>
                <item name="type">
                    <any_of>
                        <item>
                            <string value="SInt"/>
                        </item>
                        <item>
                            <string value="Int"/>
                        </item>
                        <item>
                            <string value="DInt"/>
                        </item>
                        <item>
                            <string value="LInt"/>
                        </item>
                        <item>
                            <string value="USInt"/>
                        </item>
                        <item>
                            <string value="UInt"/>
                        </item>
                        <item>
                            <string value="UDInt"/>
                        </item>
                        <item>
                            <string value="ULInt"/>
                        </item>
                        <item>
                            <string value="Real"/>
                        </item>
                        <item>
                            <string value="LReal"/>
                        </item>
                        <item>
                            <string value="Bool"/>
                        </item>
                        <item>
                            <string value="String"/>
                        </item>
                        <item>
                            <string value="Array"/>
                        </item>
                        <item>
                            <string value="Struct"/>
                        </item>
                    </any_of>
                </item>
                <item name="value">
                    <data_format_ref name="Parameters.Node.Variant"/>
                </item>
            </struct>
        </item>
    </array>
</item>
Sample
[ {
  "name" : "member1",
  "type" : "Int",
  "value" : 1
} ]

Parameters.Node.Variant

Directly referenced data formats

Parameters.Node.Array, Parameters.Node.Struct

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <int signed="true" width="64"/>
        </item>
        <item>
            <int signed="false" width="64"/>
        </item>
        <item>
            <float width="64"/>
        </item>
        <item>
            <bool/>
        </item>
        <item>
            <string/>
        </item>
        <item>
            <data_format_ref name="Parameters.Node.Struct"/>
        </item>
        <item>
            <data_format_ref name="Parameters.Node.Array"/>
        </item>
    </any_of>
</item>
Sample
1

Point

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Point2D"/>
        <data_format_ref name="Point3D"/>
    </polymorphic>
</item>

Point2D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x" desc="X coordinate">
            <float width="64"/>
        </item>
        <item name="y" desc="Y coordinate">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Point2D",
  "data" : {
    "x" : 1.0,
    "y" : 2.0
  }
}

Point3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x" desc="X coordinate">
            <float width="64"/>
        </item>
        <item name="y" desc="Y coordinate">
            <float width="64"/>
        </item>
        <item name="z" desc="Z coordinate">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Point3D",
  "data" : {
    "x" : 1.0,
    "y" : 2.0,
    "z" : 3.0
  }
}

Point3D_32

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x" desc="X coordinate">
            <float width="32"/>
        </item>
        <item name="y" desc="Y coordinate">
            <float width="32"/>
        </item>
        <item name="z" desc="Z coordinate">
            <float width="32"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Point3D_32",
  "data" : {
    "x" : 1.0,
    "y" : 2.0,
    "z" : 3.0
  }
}

PointCloud

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="PointCloud.XYZI"/>
    </polymorphic>
</item>

PointCloud.XYZI

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Width" desc="Width of the data matrix if organized, total size if not">
            <int signed="true" width="32"/>
        </item>
        <item name="Height" desc="Height of the data matrix if organized, 1 if not">
            <int signed="true" width="32"/>
        </item>
        <item name="IsDense" desc="True if no points are invalid">
            <bool/>
        </item>
        <item name="ColorMode" desc="Point cloud color mode">
            <any_of>
                <item>
                    <string value="INTENSITY"/>
                </item>
                <item>
                    <string value="RGBA"/>
                </item>
            </any_of>
        </item>
        <item name="Number" desc="Point cloud identifier (e.g. object ID or sequence number)">
            <int signed="false" width="32"/>
        </item>
        <item name="TimeStamp" desc="Time stamp in microseconds">
            <int signed="false" width="32"/>
        </item>
        <item name="SensorIDs" desc="ID(s) of the sensor(s)">
            <array>
                <item>
                    <int signed="false" width="32"/>
                </item>
            </array>
        </item>
        <item name="SensorPositions" desc="Position of the sensor(s) (x, y, z in mm)">
            <array>
                <item>
                    <data_format_ref name="Point3D_32"/>
                </item>
            </array>
        </item>
        <item name="SensorOrientations" desc="Orientation of the sensor(s) (yaw, pitch, roll in radians)">
            <array>
                <item>
                    <data_format_ref name="Point3D_32"/>
                </item>
            </array>
        </item>
        <item name="Points" desc="Each point has a size of 16 bytes, the format of the last 4 bytes depends on the ColorMode">
            <any_of>
                <item>
                    <big_data_array>
                        <element_type name="float32" desc="X coordinate"/>
                        <element_type name="float32" desc="Y coordinate"/>
                        <element_type name="float32" desc="Z coordinate"/>
                        <element_type name="float32" desc="Intensity value"/>
                    </big_data_array>
                </item>
                <item>
                    <big_data_array>
                        <element_type name="float32" desc="X coordinate"/>
                        <element_type name="float32" desc="Y coordinate"/>
                        <element_type name="float32" desc="Z coordinate"/>
                        <element_type name="uint8" desc="Red"/>
                        <element_type name="uint8" desc="Green"/>
                        <element_type name="uint8" desc="Blue"/>
                        <element_type name="uint8" desc="Alpha"/>
                    </big_data_array>
                </item>
            </any_of>
        </item>
    </struct>
</item>
Sample
{
  "class" : " PointCloud.XYZI",
  "data" : {
    "Width" : 2,
    "Height" : 1,
    "IsDense" : true,
    "ColorMode" : "INTENSITY",
    "Number" : 42,
    "TimeStamp" : 2880154539,
    "SensorIDs" : [ 1, 2 ],
    "SensorPositions" : [ {
      "x" : 1,
      "y" : 2,
      "z" : 3
    }, {
      "x" : 7,
      "y" : 8,
      "z" : 9
    } ],
    "SensorOrientations" : [ {
      "x" : 4,
      "y" : 5,
      "z" : 6
    }, {
      "x" : 10,
      "y" : 11,
      "z" : 12
    } ],
    "Points" : {
      "numOfElems" : 2,
      "elemSz" : 16,
      "endian" : "little",
      "elemTypes" : [ "float32", "float32", "float32", "float32" ],
      "data" : "AACAPwAAAEAAAEBAAACAPwAAgEAAAKBAAADAQAAAgD8="
    }
  }
}

Profile

Directly referenced data formats

Point2D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="IsClosed">
            <bool/>
        </item>
        <item name="UseValidFlags">
            <bool/>
        </item>
        <item name="Values">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="ValidFlags">
            <array>
                <item>
                    <int signed="false" width="8"/>
                </item>
            </array>
        </item>
        <item name="StartImplicit1D">
            <float width="64"/>
        </item>
        <item name="DeltaImplicit1D">
            <float width="64"/>
        </item>
        <item name="CoordinatesExplicit1D">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="StartImplicit2D">
            <data_format_ref name="Point2D"/>
        </item>
        <item name="DeltaImplicit2D">
            <data_format_ref name="Point2D"/>
        </item>
        <item name="CoordinatesExplicit2D">
            <array>
                <item>
                    <data_format_ref name="Point2D"/>
                </item>
            </array>
        </item>
        <item name="CoordinateType">
            <any_of>
                <item>
                    <string value="IMPLICIT_1D"/>
                </item>
                <item>
                    <string value="EXPLICIT_1D"/>
                </item>
                <item>
                    <string value="IMPLICIT_2D"/>
                </item>
                <item>
                    <string value="EXPLICIT_2D"/>
                </item>
            </any_of>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Profile",
  "data" : {
    "IsClosed" : false,
    "UseValidFlags" : true,
    "Values" : [ 2, 2, 2 ],
    "ValidFlags" : [ 1, 1, 1 ],
    "StartImplicit1D" : 0,
    "DeltaImplicit1D" : 1,
    "CoordinatesExplicit1D" : [ 0, 1, 2 ],
    "StartImplicit2D" : {
      "x" : 0,
      "y" : 0
    },
    "DeltaImplicit2D" : {
      "x" : 1,
      "y" : 0
    },
    "CoordinatesExplicit2D" : [ ],
    "CoordinateType" : "EXPLICIT_1D"
  }
}

Profile.Curve

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Profile.Curve.Polynomial"/>
        <data_format_ref name="Profile.Curve.Exponential"/>
        <data_format_ref name="Profile.Curve.Gaussian"/>
    </polymorphic>
</item>
Sample
{
  "class" : "Profile.Curve.Polynomial",
  "data" : {
    "coefficients" : [ 1.0, 2.0, 3.0 ]
  }
}

Profile.Curve.Exponential

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Coefficients">
            <array length="3">
                <item>
                    <float width="64"/>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Profile.Curve.Exponential",
  "data" : {
    "Coefficients" : [ 1.0, 2.0, 3.0 ]
  }
}

Profile.Curve.Gaussian

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Coefficients">
            <array length="4">
                <item>
                    <float width="64"/>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Profile.Curve.Gaussian",
  "data" : {
    "Coefficients" : [ 1.0, 2.0, 3.0, 4.0 ]
  }
}

Profile.Curve.Polynomial

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Coefficients">
            <array>
                <item>
                    <float width="64"/>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Profile.Curve.Polynomial",
  "data" : {
    "Coefficients" : [ 1.0, 2.0, 3.0 ]
  }
}

Profile.Log

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="RecentValuesEnabled">
            <bool/>
        </item>
        <item name="Values">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="Coordinates">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="Count">
            <int signed="false" width="64"/>
        </item>
        <item name="M2">
            <float width="64"/>
        </item>
        <item name="Mean">
            <float width="64"/>
        </item>
        <item name="Min">
            <float width="32"/>
        </item>
        <item name="MinCoord">
            <float width="32"/>
        </item>
        <item name="Max">
            <float width="32"/>
        </item>
        <item name="MaxCoord">
            <float width="32"/>
        </item>
        <item name="HistogramEnabled">
            <bool/>
        </item>
        <item name="Histogram">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistogramMinValue">
            <float width="32"/>
        </item>
        <item name="HistogramDelta">
            <float width="32"/>
        </item>
        <item name="RecentBack">
            <int signed="false" width="unspecified"/>
        </item>
        <item name="HistoricStatisticsEnabled">
            <bool/>
        </item>
        <item name="HistoricValueBuffer">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricCoordBuffer">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricCoordinates">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricMeanValues">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricStdDevValues">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricMaxValues">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricMinValues">
            <array>
                <item>
                    <float width="32"/>
                </item>
            </array>
        </item>
        <item name="HistoricQuanta">
            <int signed="false" width="64"/>
        </item>
        <item name="PeriodCount">
            <int signed="false" width="32"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Profile.Log",
  "data" : {
    "RecentValuesEnabled" : false,
    "Values" : [ ],
    "Coordinates" : [ ],
    "Min" : -3.200000047,
    "MinCoord" : 3.140000104,
    "Max" : 1.200000047,
    "MaxCoord" : 0,
    "Mean" : -0.5666666626930237,
    "M2" : 10.806667106946314,
    "Count" : 3,
    "HistogramEnabled" : false,
    "Histogram" : [ ],
    "HistogramMinValue" : 0,
    "HistogramDelta" : 0,
    "RecentBack" : 0,
    "HistoricStatisticsEnabled" : true,
    "HistoricValueBuffer" : [ 0.300000011 ],
    "HistoricCoordBuffer" : [ 0 ],
    "HistoricCoordinates" : [ 1.570000052 ],
    "HistoricMeanValues" : [ -1 ],
    "HistoricStdDevValues" : [ 2.200000047 ],
    "HistoricMaxValues" : [ 1.200000047 ],
    "HistoricMinValues" : [ -3.200000047 ],
    "HistoricQuanta" : 2,
    "PeriodCount" : 4
  }
}

SensorData

Directly referenced data formats

EncoderData

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Encoder" desc="Encoder data. May be optional and filled with default values when not available">
            <data_format_ref name="EncoderData"/>
        </item>
        <item name="Timestamp" desc="Application specific time stamp in microseconds">
            <int signed="false" width="64"/>
        </item>
        <item name="FrameNo" desc="Capture driver specific frame number">
            <int signed="false" width="32"/>
        </item>
        <item name="Ident" desc="Application specific ID where the corresponding image can be assigned to. Is -1 when not used or invalid.">
            <int signed="true" width="32"/>
        </item>
        <item name="Origin" desc="Dot separated list of image providers where the image originated from">
            <string/>
        </item>
        <item name="Name" desc="Name of the corresponding data object">
            <string/>
        </item>
        <item name="MetaData">
            <polymorphic can_be_null="true">
                <data_format_ref name="Container"/>
            </polymorphic>
        </item>
    </struct>
</item>
Sample
{
  "class" : "SensorData",
  "data" : {
    "Encoder" : {
      "Position" : 0,
      "Speed" : 0,
      "SystemIncrement" : 0,
      "TimestampUTC" : 0,
      "TimestampUS" : 0,
      "xValue" : 0
    },
    "Timestamp" : 0,
    "FrameNo" : 0,
    "Ident" : -1,
    "Origin" : "",
    "Name" : ""
  }
}

Shape

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Shape.Arc"/>
        <data_format_ref name="Shape.Circle"/>
        <data_format_ref name="Shape.Composite"/>
        <data_format_ref name="Shape.Ellipse"/>
        <data_format_ref name="Shape.Line"/>
        <data_format_ref name="Shape.LineSegment"/>
        <data_format_ref name="Shape.PolyLine"/>
        <data_format_ref name="Shape.Rectangle"/>
        <data_format_ref name="Shape.Sector"/>
    </polymorphic>
</item>
Sample
{
  "class" : "Shape.Circle",
  "data" : {
    "cx" : 0.0,
    "cy" : 1.0,
    "radius" : 2.0
  }
}

Shape.Arc

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="radius" desc="Radius">
            <float width="64"/>
        </item>
        <item name="angle" desc="Initial angle of the arc in radians">
            <float width="64"/>
        </item>
        <item name="deltaAngle" desc="Angular size of the arc in radians">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape.Arc",
  "data" : {
    "cx" : 10.0,
    "cy" : 10.0,
    "radius" : 1.0,
    "angle" : 0.0,
    "deltaAngle" : 3.1415927
  }
}

Shape.Circle

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="radius" desc="Radius">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape.Circle",
  "data" : {
    "cx" : 0.0,
    "cy" : 1.0,
    "radius" : 2.0
  }
}

Shape.Composite

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="shapes">
            <array>
                <item>
                    <struct>
                        <item name="isPositive">
                            <bool/>
                        </item>
                        <item name="shape">
                            <data_format_ref name="Shape"/>
                        </item>
                    </struct>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape.Composite",
  "data" : {
    "shapes" : [ {
      "isPositive" : true,
      "shape" : {
        "class" : "Shape.Circle",
        "data" : {
          "cx" : 1,
          "cy" : 2,
          "radius" : 3
        }
      }
    }, {
      "isPositive" : false,
      "shape" : {
        "class" : "Shape.Circle",
        "data" : {
          "cx" : 2,
          "cy" : 3,
          "radius" : 4
        }
      }
    } ]
  }
}

Shape.Ellipse

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="radiusX" desc="Radius in X direction">
            <float width="64"/>
        </item>
        <item name="radiusY" desc="Radius in Y direction">
            <float width="64"/>
        </item>
        <item name="orientationRad" desc="Orientation angle in radians">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape.Ellipse",
  "data" : {
    "cx" : 1.0,
    "cy" : 2.0,
    "radiusX" : 3.0,
    "radiusY" : 4.0,
    "orientationRad" : 0.0
  }
}

Shape.Line

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x1" desc="Line starting point X coordinate">
            <float width="64"/>
        </item>
        <item name="y1" desc="Line starting point Y coordinate">
            <float width="64"/>
        </item>
        <item name="xDir" desc="Direction vector X coordinate">
            <float width="64"/>
        </item>
        <item name="yDir" desc="Direction vector Y coordinate">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape.Line",
  "data" : {
    "x1" : 1.0,
    "y1" : 2.0,
    "xDir" : 1.0,
    "yDir" : 1.0
  }
}

Shape.LineSegment

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="x1" desc="Line starting point X coordinate">
            <float width="64"/>
        </item>
        <item name="y1" desc="Line starting point Y coordinate">
            <float width="64"/>
        </item>
        <item name="x2" desc="Line ending point X coordinate">
            <float width="64"/>
        </item>
        <item name="y2" desc="Line ending point X coordinate">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape.LineSegment",
  "data" : {
    "x1" : 1.0,
    "y1" : 2.0,
    "x2" : 2.0,
    "y2" : 3.0
  }
}

Shape.PolyLine

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="points">
            <array>
                <item>
                    <data_format_ref name="Point2D"/>
                </item>
            </array>
        </item>
        <item name="isClosed">
            <bool/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape.PolyLine",
  "data" : {
    "points" : [ {
      "x" : 1.0,
      "y" : 2.0
    }, {
      "x" : 3.0,
      "y" : 4.0
    } ],
    "isClosed" : false
  }
}

Shape.Rectangle

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="width" desc="Rectangle width">
            <float width="64"/>
        </item>
        <item name="height" desc="Rectangle height">
            <float width="64"/>
        </item>
        <item name="orientationRad" desc="Orientation angle in radians">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape.Rectangle",
  "data" : {
    "cx" : 1.0,
    "cy" : 2.0,
    "width" : 3.0,
    "height" : 4.0,
    "orientationRad" : 0.0
  }
}

Shape.Sector

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="cx" desc="Center point X coordinate">
            <float width="64"/>
        </item>
        <item name="cy" desc="Center point Y coordinate">
            <float width="64"/>
        </item>
        <item name="innerRadius" desc="Inner radius of the sector">
            <float width="64"/>
        </item>
        <item name="outerRadius" desc="Outer radius of the sector">
            <float width="64"/>
        </item>
        <item name="angle" desc="Initial angle of the arc in radians">
            <float width="64"/>
        </item>
        <item name="deltaAngle" desc="Angular size of the arc in radians">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape.Sector",
  "data" : {
    "cx" : 10.0,
    "cy" : 10.0,
    "innerRadius" : 1.0,
    "outerRadius" : 2.0,
    "angle" : 0.0,
    "deltaAngle" : 3.1415927
  }
}

Shape3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Shape3D.Box"/>
        <data_format_ref name="Shape3D.Circle"/>
        <data_format_ref name="Shape3D.Cone"/>
        <data_format_ref name="Shape3D.Cylinder"/>
        <data_format_ref name="Shape3D.Ellipse"/>
        <data_format_ref name="Shape3D.EllipticCylinder"/>
        <data_format_ref name="Shape3D.Line"/>
        <data_format_ref name="Shape3D.LineSegment"/>
        <data_format_ref name="Shape3D.Plane"/>
        <data_format_ref name="Shape3D.Polygon"/>
        <data_format_ref name="Shape3D.Polyline"/>
        <data_format_ref name="Shape3D.Rectangle"/>
        <data_format_ref name="Shape3D.Sphere"/>
    </polymorphic>
</item>
Sample
{
  "class" : "Shape3D.Box",
  "data" : {
    "sizeX" : 10,
    "sizeY" : 11,
    "sizeZ" : 12,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Box

Directly referenced data formats

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="sizeX" desc="Total extent of the box along its local x-direction">
            <float width="64"/>
        </item>
        <item name="sizeY" desc="Total extent of the box along its local y-direction">
            <float width="64"/>
        </item>
        <item name="sizeZ" desc="Total extent of the box along its local z-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Box",
  "data" : {
    "sizeX" : 10,
    "sizeY" : 11,
    "sizeZ" : 12,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Circle

Directly referenced data formats

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radius" desc="Radius of the circle">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Circle",
  "data" : {
    "radius" : 10,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Cone

Directly referenced data formats

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radius" desc="Radius of the cone">
            <float width="64"/>
        </item>
        <item name="height" desc="Height of the cone along its local z-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Cone",
  "data" : {
    "radius" : 10,
    "height" : 4,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Cylinder

Directly referenced data formats

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radius" desc="Radius of the cylinder">
            <float width="64"/>
        </item>
        <item name="height" desc="Height of the cylinder along its local z-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Cylinder",
  "data" : {
    "radius" : 10,
    "height" : 4,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Ellipse

Directly referenced data formats

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radiusX" desc="Radius of the ellipse in the local x-direction">
            <float width="64"/>
        </item>
        <item name="radiusY" desc="Radius of the ellipse in the local y-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Ellipse",
  "data" : {
    "radiusX" : 10,
    "radiusY" : 5,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.EllipticCylinder

Directly referenced data formats

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radiusX" desc="Radius of the elliptic cylinder in the local x-direction">
            <float width="64"/>
        </item>
        <item name="radiusY" desc="Radius of the elliptic cylinder in the local y-direction">
            <float width="64"/>
        </item>
        <item name="height" desc="Height of the elliptic cylinder in the local z-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.EllipticCylinder",
  "data" : {
    "radiusX" : 10,
    "radiusY" : 5,
    "height" : 7,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Line

Directly referenced data formats

Point3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="point" desc="A point on the line">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="direction" desc="The direction of the line, unit vector">
            <data_format_ref name="Point3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Line",
  "data" : {
    "point" : {
      "x" : 11,
      "y" : 12,
      "z" : 13
    },
    "direction" : {
      "x" : 0,
      "y" : 1,
      "z" : 0
    }
  }
}

Shape3D.LineSegment

Directly referenced data formats

Point3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="point1" desc="The first end point of the line segment">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="point2" desc="The other end point of the line segment">
            <data_format_ref name="Point3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.LineSegment",
  "data" : {
    "point1" : {
      "x" : 11,
      "y" : 12,
      "z" : 13
    },
    "point2" : {
      "x" : 10,
      "y" : -2,
      "z" : 0
    }
  }
}

Shape3D.Plane

Directly referenced data formats

Point3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="normal" desc="The plane normal">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="distance" desc="The distance from the origin to the plane">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Plane",
  "data" : {
    "normal" : {
      "x" : 11,
      "y" : 12,
      "z" : 13
    },
    "distance" : 5
  }
}

Shape3D.Polygon

Directly referenced data formats

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="points">
            <array>
                <item>
                    <data_format_ref name="Point2D"/>
                </item>
            </array>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Polygon",
  "data" : {
    "points" : [ {
      "x" : 1.0,
      "y" : 2.0
    }, {
      "x" : 4.0,
      "y" : 5.0
    } ],
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Polyline

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="points">
            <array>
                <item>
                    <data_format_ref name="Point3D"/>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Polyline",
  "data" : {
    "points" : [ {
      "x" : 1.0,
      "y" : 2.0,
      "z" : 3.0
    }, {
      "x" : 4.0,
      "y" : 5.0,
      "z" : 6.0
    } ]
  }
}

Shape3D.Rectangle

Directly referenced data formats

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="sizeX" desc="Total extent of the rectangle along its local x-direction">
            <float width="64"/>
        </item>
        <item name="sizeY" desc="Total extent of the rectangle along its local y-direction">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Rectangle",
  "data" : {
    "sizeX" : 10,
    "sizeY" : 4,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Shape3D.Sphere

Directly referenced data formats

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="radius" desc="Radius of the sphere">
            <float width="64"/>
        </item>
        <item name="pose" desc="Position and orientation of the shape">
            <data_format_ref name="Transform3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Shape3D.Sphere",
  "data" : {
    "radius" : 10,
    "pose" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    }
  }
}

Transform

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <polymorphic>
        <data_format_ref name="Transform2D"/>
        <data_format_ref name="Transform3D"/>
    </polymorphic>
</item>
Sample
{
  "class" : "Transform2D",
  "data" : {
    "Type" : "IDENTITY",
    "Matrix" : [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]
  }
}

Transform2D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Type">
            <any_of>
                <item>
                    <string value="IDENTITY"/>
                </item>
                <item>
                    <string value="TRANSLATION"/>
                </item>
                <item>
                    <string value="RIGID"/>
                </item>
                <item>
                    <string value="SIMILARITY"/>
                </item>
                <item>
                    <string value="AFFINE"/>
                </item>
                <item>
                    <string value="HOMOGRAPHY"/>
                </item>
            </any_of>
        </item>
        <item name="Matrix">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Transform2D",
  "data" : {
    "Type" : "IDENTITY",
    "Matrix" : [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]
  }
}

Transform3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Type">
            <any_of>
                <item>
                    <string value="IDENTITY"/>
                </item>
                <item>
                    <string value="TRANSLATION"/>
                </item>
                <item>
                    <string value="RIGID"/>
                </item>
                <item>
                    <string value="SIMILARITY"/>
                </item>
                <item>
                    <string value="AFFINE"/>
                </item>
                <item>
                    <string value="HOMOGRAPHY"/>
                </item>
            </any_of>
        </item>
        <item name="Matrix">
            <array>
                <item>
                    <array>
                        <item>
                            <float width="64"/>
                        </item>
                    </array>
                </item>
            </array>
        </item>
    </struct>
</item>
Sample
{
  "class" : "Transform3D",
  "data" : {
    "Type" : "IDENTITY",
    "Matrix" : [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]
  }
}

View.Camera

Directly referenced data formats

Point3D

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Position">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="Target">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="Up">
            <data_format_ref name="Point3D"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.Camera",
  "data" : {
    "Position" : {
      "x" : 0,
      "y" : -1,
      "z" : 2000
    },
    "Target" : {
      "x" : 0,
      "y" : 0,
      "z" : 0
    },
    "Up" : {
      "x" : 0,
      "y" : 0,
      "z" : 1
    },
    "PositionSet" : true,
    "TargetSet" : true,
    "UpSet" : true
  }
}

View.ColorMap

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="ColorMapType">
            <any_of>
                <item>
                    <string value="LINEAR"/>
                </item>
                <item>
                    <string value="DISCRETE"/>
                </item>
            </any_of>
        </item>
        <item name="ColorStops">
            <array>
                <item>
                    <struct>
                        <item name="Value">
                            <float width="64"/>
                        </item>
                        <item name="R">
                            <int signed="false" width="8"/>
                        </item>
                        <item name="G">
                            <int signed="false" width="8"/>
                        </item>
                        <item name="B">
                            <int signed="false" width="8"/>
                        </item>
                        <item name="A">
                            <int signed="false" width="8"/>
                        </item>
                    </struct>
                </item>
            </array>
        </item>
        <item name="RangeStart">
            <float width="64"/>
        </item>
        <item name="RangeStop">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.ColorMap",
  "data" : {
    "ColorMapType" : "LINEAR",
    "ColorStops" : [ {
      "Value" : 0.0,
      "R" : 255,
      "G" : 0,
      "B" : 0,
      "A" : 255
    }, {
      "Value" : 1.0,
      "R" : 0,
      "G" : 255,
      "B" : 0,
      "A" : 255
    } ],
    "Id" : 6235,
    "RangeStart" : 0.0,
    "RangeStop" : 1.0
  }
}

View.GraphDecoration

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="AxisColor">
            <data_format_ref name="View.GraphDecoration.RGBA"/>
        </item>
        <item name="BackgroundColor">
            <data_format_ref name="View.GraphDecoration.RGBA"/>
        </item>
        <item name="GraphColor">
            <data_format_ref name="View.GraphDecoration.RGBA"/>
        </item>
        <item name="GridColor">
            <data_format_ref name="View.GraphDecoration.RGBA"/>
        </item>
        <item name="LabelColor">
            <data_format_ref name="View.GraphDecoration.RGBA"/>
        </item>
        <item name="GraphType">
            <data_format_ref name="View.GraphDecoration.GRAPHTYPE"/>
        </item>
        <item name="AspectRatio">
            <data_format_ref name="View.GraphDecoration.ASPECTRATIO"/>
        </item>
        <item name="AxisVisible">
            <bool/>
        </item>
        <item name="BackgroundVisible">
            <bool/>
        </item>
        <item name="GridVisible">
            <bool/>
        </item>
        <item name="LabelsVisible">
            <bool/>
        </item>
        <item name="TicksVisible">
            <bool/>
        </item>
        <item name="UseIndexCoordinates">
            <bool/>
        </item>
        <item name="UsePolarPlot">
            <bool/>
        </item>
        <item name="DynamicSizing">
            <bool/>
        </item>
        <item name="DrawSize">
            <float width="32"/>
        </item>
        <item name="AxisWidth">
            <float width="32"/>
        </item>
        <item name="LabelSize">
            <float width="32"/>
        </item>
        <item name="TitleSize">
            <float width="32"/>
        </item>
        <item name="LowerXBound">
            <float width="32"/>
        </item>
        <item name="LowerYBound">
            <float width="32"/>
        </item>
        <item name="UpperXBound">
            <float width="32"/>
        </item>
        <item name="UpperYBound">
            <float width="32"/>
        </item>
        <item name="XLabel">
            <string/>
        </item>
        <item name="YLabel">
            <string/>
        </item>
        <item name="Title">
            <string/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.GraphDecoration",
  "data" : {
    "AxisColor" : {
      "R" : 255,
      "G" : 255,
      "B" : 0,
      "A" : 255
    },
    "BackgroundColor" : {
      "R" : 255,
      "G" : 0,
      "B" : 255,
      "A" : 255
    },
    "GraphColor" : {
      "R" : 0,
      "G" : 255,
      "B" : 255,
      "A" : 255
    },
    "GridColor" : {
      "R" : 255,
      "G" : 255,
      "B" : 0,
      "A" : 0
    },
    "LabelColor" : {
      "R" : 0,
      "G" : 255,
      "B" : 0,
      "A" : 255
    },
    "GraphType" : "DOT",
    "AspectRatio" : "EQUAL",
    "AxisVisible" : false,
    "BackgroundVisible" : false,
    "GridVisible" : false,
    "LabelsVisible" : false,
    "TicksVisible" : false,
    "UseIndexCoordinates" : true,
    "UsePolarPlot" : true,
    "DynamicSizing" : true,
    "DrawSize" : 5,
    "AxisWidth" : 2.5,
    "LabelSize" : 7,
    "TitleSize" : 9,
    "LowerXBound" : -100,
    "LowerYBound" : -200,
    "UpperXBound" : 100,
    "UpperYBound" : 200,
    "XLabel" : "x-axis",
    "YLabel" : "y-axis",
    "Title" : "Test Title"
  }
}

View.GraphDecoration.ASPECTRATIO

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <string value="EQUAL"/>
        </item>
        <item>
            <string value="SQUARE"/>
        </item>
        <item>
            <string value="FIT"/>
        </item>
    </any_of>
</item>

View.GraphDecoration.GRAPHTYPE

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <string value="DOT"/>
        </item>
        <item>
            <string value="LINE"/>
        </item>
        <item>
            <string value="BAR"/>
        </item>
    </any_of>
</item>

View.GraphDecoration.RGBA

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="R" desc="Red component">
            <int signed="false" width="8"/>
        </item>
        <item name="G" desc="Green component">
            <int signed="false" width="8"/>
        </item>
        <item name="B" desc="Blue component">
            <int signed="false" width="8"/>
        </item>
        <item name="A" desc="Alpha component">
            <int signed="false" width="8"/>
        </item>
    </struct>
</item>

View.ImageDecoration

Directly referenced data formats

View.ImageDecoration.DataRange

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="DataRange">
            <data_format_ref name="View.ImageDecoration.DataRange"/>
        </item>
        <item name="ColorMap">
            <int signed="true" width="32"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.ImageDecoration",
  "data" : {
    "DataRange" : {
      "Min" : 0,
      "Max" : 255
    },
    "ColorMap" : 0
  }
}

View.ImageDecoration.DataRange

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Min">
            <float width="64"/>
        </item>
        <item name="Max">
            <float width="64"/>
        </item>
    </struct>
</item>

View.MeshDecoration

Directly referenced data formats

View.MeshDecoration.VisibleFaces

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="SurfaceColor">
            <struct>
                <item name="R" desc="Red component">
                    <int signed="false" width="8"/>
                </item>
                <item name="G" desc="Green component">
                    <int signed="false" width="8"/>
                </item>
                <item name="B" desc="Blue component">
                    <int signed="false" width="8"/>
                </item>
                <item name="A" desc="Alpha component">
                    <int signed="false" width="8"/>
                </item>
            </struct>
        </item>
        <item name="VisibleFaces">
            <data_format_ref name="View.MeshDecoration.VisibleFaces"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.MeshDecoration",
  "data" : {
    "SurfaceColor" : {
      "R" : 255,
      "G" : 255,
      "B" : 255,
      "A" : 255
    },
    "VisibleFaces" : "FRONT_AND_BACK"
  }
}

View.MeshDecoration.VisibleFaces

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <string value="FRONT"/>
        </item>
        <item>
            <string value="BACK"/>
        </item>
        <item>
            <string value="FRONT_AND_BACK"/>
        </item>
        <item>
            <string value="NONE"/>
        </item>
    </any_of>
</item>

View.PixelRegionDecoration

Directly referenced data formats

View.PixelRegionDecoration.RGBA

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Color">
            <data_format_ref name="View.PixelRegionDecoration.RGBA"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.PixelRegionDecoration",
  "data" : {
    "Color" : {
      "R" : 0,
      "G" : 127,
      "B" : 195,
      "A" : 255
    }
  }
}

View.PixelRegionDecoration.RGBA

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="R" desc="Red component">
            <int signed="false" width="8"/>
        </item>
        <item name="G" desc="Green component">
            <int signed="false" width="8"/>
        </item>
        <item name="B" desc="Blue component">
            <int signed="false" width="8"/>
        </item>
        <item name="A" desc="Alpha component">
            <int signed="false" width="8"/>
        </item>
    </struct>
</item>

View.PointCloudDecoration

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="XMax">
            <float width="64"/>
        </item>
        <item name="YMax">
            <float width="64"/>
        </item>
        <item name="ZMax">
            <float width="64"/>
        </item>
        <item name="IMax">
            <float width="64"/>
        </item>
        <item name="XMin">
            <float width="64"/>
        </item>
        <item name="YMin">
            <float width="64"/>
        </item>
        <item name="ZMin">
            <float width="64"/>
        </item>
        <item name="IMin">
            <float width="64"/>
        </item>
        <item name="XRangeSet">
            <bool/>
        </item>
        <item name="YRangeSet">
            <bool/>
        </item>
        <item name="ZRangeSet">
            <bool/>
        </item>
        <item name="IRangeSet">
            <bool/>
        </item>
        <item name="XColorMap">
            <int signed="true" width="32"/>
        </item>
        <item name="YColorMap">
            <int signed="true" width="32"/>
        </item>
        <item name="ZColorMap">
            <int signed="true" width="32"/>
        </item>
        <item name="IColorMap">
            <int signed="true" width="32"/>
        </item>
        <item name="PointSize">
            <float width="64"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.PointCloudDecoration",
  "data" : {
    "XMax" : 100,
    "YMax" : 100,
    "ZMax" : 100,
    "IMax" : 100,
    "XMin" : -100,
    "YMin" : -100,
    "ZMin" : -100,
    "IMin" : -100,
    "XRangeSet" : true,
    "YRangeSet" : true,
    "ZRangeSet" : true,
    "IRangeSet" : true,
    "XColorMap" : 0,
    "YColorMap" : 0,
    "ZColorMap" : 0,
    "IColorMap" : 0,
    "PointSize" : 1
  }
}

View.Present.Add

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Type">
            <any_of>
                <item>
                    <string value="HEIGHTMAP"/>
                </item>
                <item>
                    <string value="IMAGE"/>
                </item>
                <item>
                    <string value="PIXEL_REGION"/>
                </item>
                <item>
                    <string value="POINT_CLOUD"/>
                </item>
                <item>
                    <string value="SHAPE"/>
                </item>
                <item>
                    <string value="TEXT"/>
                </item>
                <item>
                    <string value="PROFILE"/>
                </item>
                <item>
                    <string value="POLAR_SCAN"/>
                </item>
                <item>
                    <string value="MESH"/>
                </item>
                <item>
                    <string value="CAMERAMODEL"/>
                </item>
                <item>
                    <string value="UNDEFINED"/>
                </item>
            </any_of>
        </item>
        <item name="Iconics">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="Decorations">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="CameraModel">
            <polymorphic can_be_null="true">
                <data_format_ref name="Image.Calibration.CameraModel"/>
            </polymorphic>
        </item>
        <item name="Labels">
            <array>
                <item>
                    <string/>
                </item>
            </array>
        </item>
        <item name="IconicId">
            <string/>
        </item>
        <item name="ParentId">
            <string/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.Present.Add",
  "data" : {
    "Type" : "SHAPE",
    "Iconics" : [ {
      "class" : "Shape.Circle",
      "data" : {
        "cx" : 3,
        "cy" : 3,
        "radius" : 4
      }
    } ],
    "Decorations" : [ {
      "class" : "View.ShapeDecoration",
      "data" : {
        "LineColor" : {
          "R" : 0,
          "G" : 127,
          "B" : 195,
          "A" : 255
        },
        "FillColor" : {
          "R" : 0,
          "G" : 127,
          "B" : 195,
          "A" : 0
        },
        "LineWidth" : 1,
        "PointSize" : 3,
        "PointType" : "DOT"
      }
    } ],
    "CameraModel" : null,
    "Labels" : [ ],
    "IconicId" : "_ID_ICONIC_2",
    "ParentId" : "_ID_ICONIC_1"
  }
}

View.Present.Clear

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct/>
</item>
Sample
{
  "class" : "View.Present.Clear",
  "data" : { }
}

View.Present.Editor

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Type">
            <any_of>
                <item>
                    <string value="INSTALL"/>
                </item>
                <item>
                    <string value="UNINSTALL"/>
                </item>
            </any_of>
        </item>
        <item name="IconicId">
            <string/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.Present.Editor",
  "data" : {
    "Type" : "INSTALL",
    "IconicId" : "_ID_ICONIC_1"
  }
}

View.Present.Remove

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="IconicId">
            <string/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.Present.Remove",
  "data" : {
    "IconicId" : "_ID_ICONIC_1"
  }
}

View.Present.UpdateDecoration

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Decorations">
            <array>
                <item>
                    <polymorphic/>
                </item>
            </array>
        </item>
        <item name="IconicId">
            <string/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.Present.UpdateDecoration",
  "data" : {
    "Decoration" : {
      "class" : "View.ShapeDecoration",
      "data" : {
        "LineColor" : {
          "R" : 0,
          "G" : 127,
          "B" : 195,
          "A" : 255
        },
        "FillColor" : {
          "R" : 0,
          "G" : 127,
          "B" : 195,
          "A" : 0
        },
        "LineWidth" : 1,
        "PointSize" : 3,
        "PointType" : "DOT"
      }
    },
    "IconicId" : "_ID_ICONIC_2"
  }
}

View.Present.UpdateTransform

Directly referenced data formats

Transform

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Pose">
            <data_format_ref name="Transform"/>
        </item>
        <item name="IconicId">
            <string/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.Present.UpdateTransform",
  "data" : {
    "Transform" : {
      "Type" : "TRANSLATION",
      "Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
    },
    "IconicId" : "_ID_ICONIC_2"
  }
}

View.ShapeDecoration

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="LineColor">
            <data_format_ref name="View.ShapeDecoration.Pixel.RGBA"/>
        </item>
        <item name="FillColor">
            <data_format_ref name="View.ShapeDecoration.Pixel.RGBA"/>
        </item>
        <item name="LineWidth">
            <float width="32"/>
        </item>
        <item name="PointSize">
            <float width="32"/>
        </item>
        <item name="PointType">
            <data_format_ref name="View.ShapeDecoration.PointType"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.ShapeDecoration",
  "data" : {
    "LineColor" : {
      "R" : 0,
      "G" : 127,
      "B" : 195,
      "A" : 255
    },
    "FillColor" : {
      "R" : 0,
      "G" : 127,
      "B" : 195,
      "A" : 0
    },
    "LineWidth" : 1,
    "PointSize" : 3,
    "PointType" : "DOT"
  }
}

View.ShapeDecoration.Pixel.RGBA

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="R" desc="Red component">
            <int signed="false" width="8"/>
        </item>
        <item name="G" desc="Green component">
            <int signed="false" width="8"/>
        </item>
        <item name="B" desc="Blue component">
            <int signed="false" width="8"/>
        </item>
        <item name="A" desc="Alpha component">
            <int signed="false" width="8"/>
        </item>
    </struct>
</item>

View.ShapeDecoration.PointType

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <string value="DOT"/>
        </item>
        <item>
            <string value="CROSS"/>
        </item>
    </any_of>
</item>

View.TextDecoration

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="FontSize">
            <int signed="true" width="64"/>
        </item>
        <item name="Position">
            <data_format_ref name="Point3D_32"/>
        </item>
        <item name="HorizontalAlignment">
            <data_format_ref name="View.TextDecoration.HorizontalAlignment"/>
        </item>
        <item name="VerticalAlignment">
            <data_format_ref name="View.TextDecoration.VerticalAlignment"/>
        </item>
        <item name="FontWeight">
            <data_format_ref name="View.TextDecoration.FontWeight"/>
        </item>
        <item name="FontFamily">
            <data_format_ref name="View.TextDecoration.FontFamily"/>
        </item>
        <item name="Rotation">
            <float width="64"/>
        </item>
        <item name="RotationAxis">
            <data_format_ref name="Point3D"/>
        </item>
        <item name="BillboardActive">
            <bool/>
        </item>
        <item name="Bounds">
            <data_format_ref name="View.TextDecoration.Bounds"/>
        </item>
        <item name="LineSpacing">
            <float width="64"/>
        </item>
        <item name="Color">
            <data_format_ref name="View.TextDecoration.RGBA"/>
        </item>
    </struct>
</item>
Sample
{
  "class" : "View.TextDecoration",
  "data" : {
    "FontSize" : 10,
    "Position" : {
      "x" : 0,
      "y" : 0,
      "z" : 0
    },
    "HorizontalAlignment" : "LEFT",
    "VerticalAlignment" : "BOTTOM",
    "FontWeight" : "NORMAL",
    "FontFamily" : "SANSSERIF",
    "Rotation" : 0,
    "RotationAxis" : {
      "x" : 0,
      "y" : 0,
      "z" : 0
    },
    "BillboardActive" : true,
    "Bounds" : {
      "Width" : 42,
      "Height" : 46
    },
    "LineSpacing" : 1.1,
    "Color" : {
      "R" : 0,
      "G" : 127,
      "B" : 195,
      "A" : 255
    }
  }
}

View.TextDecoration.Bounds

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="Width" desc="Width component">
            <int signed="false" width="32"/>
        </item>
        <item name="Height" desc="Height component">
            <int signed="false" width="32"/>
        </item>
    </struct>
</item>

View.TextDecoration.FontFamily

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <string value="SANSSERIF"/>
        </item>
        <item>
            <string value="MONOSPACE"/>
        </item>
        <item>
            <string value="SERIF"/>
        </item>
    </any_of>
</item>

View.TextDecoration.FontWeight

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <string value="NORMAL"/>
        </item>
        <item>
            <string value="BOLD"/>
        </item>
    </any_of>
</item>

View.TextDecoration.HorizontalAlignment

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <string value="LEFT"/>
        </item>
        <item>
            <string value="CENTERH"/>
        </item>
        <item>
            <string value="RIGHT"/>
        </item>
        <item>
            <string value="JUSTIFY"/>
        </item>
    </any_of>
</item>

View.TextDecoration.RGBA

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <struct>
        <item name="R" desc="Red component">
            <int signed="false" width="8"/>
        </item>
        <item name="G" desc="Green component">
            <int signed="false" width="8"/>
        </item>
        <item name="B" desc="Blue component">
            <int signed="false" width="8"/>
        </item>
        <item name="A" desc="Alpha component">
            <int signed="false" width="8"/>
        </item>
    </struct>
</item>

View.TextDecoration.VerticalAlignment

Specification
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
    <any_of>
        <item>
            <string value="BOTTOM"/>
        </item>
        <item>
            <string value="CENTERV"/>
        </item>
        <item>
            <string value="TOP"/>
        </item>
    </any_of>
</item>